DiscordVFS mounts the Discord servers a bot is in as read-only files: each
channel as one folder per day of messages and attachments, plus members. Set up the bot token as in Discord setup.
Install
Configure
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.
Discord API root; override to point at a fake or proxy.
Authentication
token is a bot token, sent with Discord’s Bot <token> scheme. The bot
needs:
- Message Content Intent: without it, message text and attachments come back empty.
- Server Members Intent: for the
members/folder; without it,members/is empty. - The View Channels and Read Message History permissions in each server it reads. The mount never posts.
Permission denied: ls names it and
fails, find reports it and walks on. A channel deleted since it was listed
answers No such file or directory.
Layout
- Names: a server, channel, member or attachment is
<display-name>__<id>, so the CLI’s flags take the snowflake id from the path and two entities with one name never collide. Spaces, apostrophes and emoji are kept; only/becomes∕(U+2215). Quote names with spaces.statalso shows the id. - Servers: the root lists one folder per server the bot is in.
channels/: text channels (types 0, 5 and 15), each with one folder per day for the 30 days up to its newest message, so an inactive channel shows days around its last activity, not today.chat.jsonl: one message per line as Discord’s API returns it, with.id,.content,.author.usernameand.attachments.files/: the attachments posted that day, named<stem>__<attachment-id>.<ext>.catdownloads one from Discord’s CDN.members/: one file per member, holding the member as Discord’s API returns it.
Behavior
- Read only: the mount cannot send or change messages. Use the
discordCLI to send, edit, react, open threads and polls, look up members and servers, and search. - Search:
grep -randrgread every day’schat.jsonlunder the folder they walk, one history fetch per day, so name a day folder or a date glob for a large channel. Discord’s own search is not used: it cannot say which days hold a word, since a reply carries the message it answers (referenced_message). - Time scope:
startTimeandendTimebound the mount with RFC 3339 timestamps that carry a timezone, at most to the millisecond. Start is inclusive, end exclusive, and an unset bound is open. Listings then cover that period instead of the recent window, day folders use UTC, messages are picked by creation time and attachments follow their messages. Direct paths,stat, date globs,grepandrgcannot leave the scope. Members and server metadata stay visible. The scope applies to the mount, not to thediscordCLI; rebuild the mount to change it. - Upstream changes: a
readmount refuses writes through Mirage; it does not freeze edits or deletions made in Discord. - Rate limits: many reads of
chat.jsonlcan hit Discord’s per-route rate limits. A read that gets a 429 waits theretry_afterDiscord sends and retries; one that outlasts the retries fails, so slow down or name specific channels.
Browser
The browserDiscordVFS from @struktoai/mirage-browser never sees the
token: a proxy on the backend holds it and forwards /api/discord/* to
https://discord.com/api/v10/*.
- The proxy is required: Discord sets no permissive CORS headers for the bot
API, so a call to
https://discord.com/api/v10/*from the page fails. - The proxy sends
Authorization: Bot <token>, notBearer;Beareranswers401 Unauthorized. 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://discord.com/api/v10 and attaches the bot 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
Discord answers this command through its own API, so less is read. See Integration.tail -f: each new message as it is posted.
VFS.md
The VFS.md an agent reads with Discord mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- A guild, channel, member or attachment 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 (.content,.author.username,.attachments).- Without
start_time/end_time, a channel lists the 30 days up to its newest message; a date glob finds earlier days. grep -ron a channel reads every listed day, attachments included; they download from the CDN and binary ones produce noise.
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.