Skip to main content
SlackVFS mounts a Slack workspace as read-only files: channels and DMs as one folder per day of messages and attachments, plus user profiles. Set up the tokens as in Slack setup.

Install

Configure

searchToken is optional: without it, grep reads the files. startTime and endTime bound the mount to a time range.

Fields

string
Start of the mount’s time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.
string
End of the mount’s time scope, exclusive, in the same format as startTime, which it must follow. Unset leaves the end open.
number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
required
secret
Slack token every API call sends: a bot token (xoxb-) or a user token (xoxp-).
string
secret
User token (xoxp-) with search:read, used only for Slack’s search.* methods, which refuse a bot token. Unset searches with token.
string
default:"'https://slack.com/api'"
Slack Web API root; override to point at a fake or proxy.
Fields marked secret are redacted in snapshots.

Authentication

token is a bot token (xoxb-...) with these bot scopes:
  • channels:read, channels:history: public channels.
  • groups:read, groups:history: private channels (optional).
  • im:read, im:history: direct messages (optional).
  • mpim:read, mpim:history: group DMs (optional).
  • users:read: the users/ folder.
  • files:read: attachments under files/.
Invite the bot to each channel it should read with /invite @Mirage; a channel it is not in answers Permission denied. The mount never posts. Slack’s search refuses bot tokens (not_allowed_token_type). The optional searchToken is a user token (xoxp-...) with search:read, used only for Slack’s search methods; the bot token still does every read. For grep and rg, that user token also needs channels:read, groups:read, im:read and mpim:read, so Mirage can tell which channels and DMs its search covers.

Layout

  • Names: a channel, DM or user is <display-name>__<id>, so the CLI’s channel and user flags take the id from the path. Only / in a name becomes ∕ (U+2215); ls the parent for exact names and quote names with spaces.
  • Days: each channel and DM lists one folder per day for the 90 days up to its newest message; a date glob finds earlier days.
  • chat.jsonl: one message per line as Slack’s API returns it (.text, .user, .ts, .files). .user is a user id, matched against users/<name>__<user-id>.json.
  • files/: the attachments shared that day.
  • users/: one file per user that is not deleted or a bot, holding the full profile from Slack.

Behavior

  • Read only: the mount cannot send or change messages. Use the slack CLI to send messages, react, pin, look up members, search and upload files.
  • Time scope: startTime and endTime (RFC 3339 with a timezone) limit the mount to that period; start inclusive, end exclusive, an unset bound open.
    • Day folders use UTC, and messages are picked by creation time. Direct paths, stat, date globs, grep and rg stay inside the scope. Users and channel metadata stay visible.
    • The scope does not apply to the slack CLI. Rebuild the mount to change it.
  • Upstream changes: a read mount refuses writes through Mirage; it does not freeze edits or deletions made in Slack.
  • Rate limits: many reads of chat.jsonl can hit Slack’s per-method rate limits, and history limits depend on how the app is distributed; see Slack’s conversations.history limits.

Browser

The browser SlackVFS from @struktoai/mirage-browser never sees a token: a proxy on the backend holds it and forwards /api/slack/* to https://slack.com/api/*.
  • The proxy is required: Slack sets no permissive CORS headers, so a call to https://slack.com/api/* from the page fails.
  • getHeaders returns extra headers for each request to the proxy, such as a per-user session credential.
string
Start of the mount’s time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.
string
End of the mount’s time scope, exclusive, in the same format as startTime, which it must follow. Unset leaves the end open.
number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
required
URL of your backend proxy, which forwards to https://slack.com/api and attaches the token. A path resolves against the page’s origin; no query string or fragment.
function
secret
Function returning extra headers sent with every request to the proxy, such as your own session credential.
Fields marked secret are redacted in snapshots.

Integration

Slack answers these commands through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: with a user token, only the channel and DM days Slack search names are read, and the output matches reading every day. Search covers message text, file names and titles, and reactions (has::name:); a file hit names each day the file was shared. Users, file blobs and a day searched on its own are always read. Every day is read when the word is a key or fixed value of the message JSON, a file-type or URL word, a join or leave message word, or part of a user’s name or of the workspace’s domain, and when a search fails, returns more than 1,000 messages or finds nothing. With a separate searchToken, every day is also read when the scope holds a private channel or DM that token’s user is not in (a bot’s own DMs). Slack indexes a message some time after it is posted, and a word held only in another field (a bot’s username, an unfurled link) is not searched; walk_limit: -1 in the mount’s "@all" command limit reads every file instead.
  • tail -f: each new message as it is posted.

VFS.md

The VFS.md an agent reads with Slack mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • A channel, DM or user name is <display-name>__<id>; only / becomes ∕ (U+2215). ls the parent for exact names and quote names with spaces.
  • chat.jsonl holds one message per line (.text, .user, .ts, .files). .user is a user id (U…); match it against users/<username>__<user-id>.json.
  • Without start_time/end_time, a channel lists the 90 days up to its newest message; a date glob finds earlier days.
  • Unless walk_limit is -1, grep -rw and rg -w read only the days Slack search names; files/ is always read.
Time scope: start_time=unbounded (inclusive), end_time=unbounded (exclusive); explicit paths and globs cannot escape it.Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.