Skip to main content
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

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
Discord bot token, sent as Authorization: Bot <token>.
string
default:"'https://discord.com/api/v10'"
Discord API root; override to point at a fake or proxy.
Fields marked secret are redacted in snapshots.

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.
A channel the bot cannot read answers 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. stat also 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.username and .attachments.
  • files/: the attachments posted that day, named <stem>__<attachment-id>.<ext>. cat downloads 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 discord CLI to send, edit, react, open threads and polls, look up members and servers, and search.
  • Search: grep -r and rg read every day’s chat.jsonl under 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: startTime and endTime bound 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, grep and rg cannot leave the scope. Members and server metadata stay visible. The scope applies to the mount, not to the discord 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 Discord.
  • Rate limits: many reads of chat.jsonl can hit Discord’s per-route rate limits. A read that gets a 429 waits the retry_after Discord sends and retries; one that outlasts the retries fails, so slow down or name specific channels.

Browser

The browser DiscordVFS 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>, not Bearer; Bearer answers 401 Unauthorized.
  • 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://discord.com/api/v10 and attaches the bot 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

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>.
Virtual FilesystemVFS Layout/<path>
  • A guild, channel, member or attachment 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 (.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 -r on a channel reads every listed day, attachments included; they download from the CDN and binary ones produce noise.
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.