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
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.
End of the mount’s time scope, exclusive, in the same format as
startTime, which it must follow. Unset leaves the end open.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.
User token (
xoxp-) with search:read, used only for Slack’s search.* methods, which refuse a bot token. Unset searches with token.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: theusers/folder.files:read: attachments underfiles/.
/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);lsthe 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)..useris a user id, matched againstusers/<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
slackCLI to send messages, react, pin, look up members, search and upload files. - Time scope:
startTimeandendTime(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,grepandrgstay inside the scope. Users and channel metadata stay visible. - The scope does not apply to the
slackCLI. Rebuild the mount to change it.
- Day folders use UTC, and messages are picked by creation time. Direct
paths,
- Upstream changes: a
readmount refuses writes through Mirage; it does not freeze edits or deletions made in Slack. - Rate limits: many reads of
chat.jsonlcan hit Slack’s per-method rate limits, and history limits depend on how the app is distributed; see Slack’sconversations.historylimits.
Browser
The browserSlackVFS 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. getHeadersreturns extra headers for each request to the proxy, such as a per-user session credential.
Proxy server
Proxy server
Browser fields
Browser fields
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.
End of the mount’s time scope, exclusive, in the same format as
startTime, which it must follow. Unset leaves the end open.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.
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 returning extra headers sent with every request to the proxy, such as your own session credential.
Integration
Slack answers these commands through its own API, so fewer files are read. See Integration.grep -rwandrg -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 separatesearchToken, 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: -1in 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>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- A channel, DM or user name is
<display-name>__<id>; only/becomes∕(U+2215).lsthe parent for exact names and quote names with spaces. chat.jsonlholds one message per line (.text,.user,.ts,.files)..useris a user id (U…); match it againstusers/<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_limitis -1,grep -rwandrg -wread only the days Slack search names;files/is always read.
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.