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

start_time and end_time bound the mount to a time range.

Fields

str
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.
str
End of the mount’s time scope, exclusive, in the same format as start_time, which it must follow. Unset leaves the end open.
float
default:"30"
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.
str
required
secret
Discord bot token, sent as Authorization: Bot <token>.
str
Discord API root. Unset uses https://discord.com/api/v10; set it 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: start_time and end_time 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.

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.