Discord

The Discord VFS exposes guild, channel, and member data as a virtual filesystem mounted at some prefix such as /discord/. For token setup, see Discord Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.discord import DiscordConfig, DiscordVFS

config = DiscordConfig(token=os.environ["DISCORD_BOT_TOKEN"])
vfs = DiscordVFS(config=config)
ws = Workspace({"/discord": vfs}, mode=MountMode.READ)

Field	Description
`start_time`	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_time`	End of the mount’s time scope, exclusive, in the same format as `start_time`, which it must follow. Unset leaves the end open.
`timeout` 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.
`token` required, secret	Discord bot token, sent as `Authorization: Bot <token>`.
`base_url`	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.

VFS.md

The VFS.md an agent reads with Discord mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`discord`, read

VFS Layout

`/<path>`

/<path>
  <guild-name>__<guild-id>/
    channels/
      <channel-name>__<channel-id>/
        <yyyy-mm-dd>/
          chat.jsonl                # messages for that date
          files/                    # attachments shared that day
            <name>__<att-id>.<ext>  # cat downloads it from Discord's CDN
    members/
      <username>__<user-id>.json    # member profile

A guild, channel, member or attachment name is <display-name>__<id>. The display name keeps Discord’s spelling (spaces, apostrophes, emoji); only / becomes ∕ (U+2215). ls the parent first to find exact names, and quote a name that has spaces.
Messages are JSONL; use jq for fields such as .content, .author.username and .attachments. A day’s files/ may be empty.
Without start_time/end_time, a channel lists the latest 30 days up to its newest message; a date glob finds earlier days.
With start_time/end_time, listings cover that scope; messages and attachments outside it are absent, direct paths included. Users and channel metadata stay available as context.
grep and rg read the files they reach, so grep needs -r for a directory. Under a channel that reads every listed day, attachments included: they download from the CDN, and binary ones such as JPG or PDF produce noise.

Time scope: start_time=unbounded (inclusive), end_time=unbounded (exclusive). Explicit paths and globs cannot escape this scope.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest).

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `discord`, read |

## VFS Layout

### `/<path>`

```text
/<path>
  <guild-name>__<guild-id>/
    channels/
      <channel-name>__<channel-id>/
        <yyyy-mm-dd>/
          chat.jsonl                # messages for that date
          files/                    # attachments shared that day
            <name>__<att-id>.<ext>  # cat downloads it from Discord's CDN
    members/
      <username>__<user-id>.json    # member profile
```

- A guild, channel, member or attachment name is `<display-name>__<id>`.
  The display name keeps Discord's spelling (spaces, apostrophes, emoji);
  only `/` becomes `∕` (U+2215). `ls` the parent first to find exact
  names, and quote a name that has spaces.
- Messages are JSONL; use `jq` for fields such as `.content`,
  `.author.username` and `.attachments`. A day's `files/` may be empty.
- Without `start_time`/`end_time`, a channel lists the latest 30 days up
  to its newest message; a date glob finds earlier days.
- With `start_time`/`end_time`, listings cover that scope; messages and
  attachments outside it are absent, direct paths included. Users and
  channel metadata stay available as context.
- `grep` and `rg` read the files they reach, so `grep` needs `-r` for a
  directory. Under a channel that reads every listed day, attachments
  included: they download from the CDN, and binary ones such as JPG or
  PDF produce noise.

Time scope: `start_time=unbounded` (inclusive), `end_time=unbounded` (exclusive). Explicit paths and globs cannot escape this scope.

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Display names keep their original spelling from Discord (spaces, apostrophes, emoji are all preserved). Only / is replaced with ∕ (U+2215) so it cannot collide with a directory boundary. The Discord snowflake ID is appended after __ (double underscore) on guild, channel, member, and attachment names so VFS specific commands can extract it without an extra lookup, and so two same named entities never collide. Quote names containing spaces in shell commands. stat also exposes the ID in the extra dict (see Finding IDs).

Guilds

The root lists one directory per guild the bot has access to.

Channels

/discord/<guild>/channels/ lists text channels (types 0, 5, 15). Each channel directory contains day-partitioned directories for the 30 days leading up to the channel’s last message. Each day directory holds:

chat.jsonl, the day’s messages (one JSON object per line).
files/, attachments posted on that day. Each blob is named <stem>__<attachment-id>.<ext>, where the stem keeps the original filename’s spelling (only / is replaced). The ID suffix keeps the filename collision-free. cat’ing a blob downloads it from the Discord CDN.

The date range is derived from last_message_id on the channel object, so inactive channels show dates around their last activity, not today. Soft errors (403 missing permissions, 404 unknown channel, 429 rate limit) on a single day are swallowed so listings, find, and grep keep working across the rest of the tree.

Members

/discord/<guild>/members/ lists one .json file per member. Reading a member file returns the full member payload from the Discord API.

Smart Commands

grep / rg

grep -r and rg read every day’s chat.jsonl under the directory they walk, so a channel or guild costs one history fetch per day. Name a day directory or a date glob to search a large channel. Discord’s own search is not used: a reply carries the message it answers (referenced_message), which that search does not tie to the reply’s day, so it cannot say which days hold a word.

head / tail

head and tail on file-level paths use the Discord messages API directly (GET /channels/{id}/messages) instead of downloading the full day’s history.

Cache

The Discord VFS uses IndexCacheStore (same as S3, disk and GitHub). Index entries store guild IDs, channel IDs, and last_message_id for date range computation. File bytes go through the workspace file cache.

Integration

What Discord answers through its own API, so fewer files are read. Integration explains each command.

Command	On Discord
`tail -f`	Each new message as it is posted

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.discord import DiscordConfig, DiscordVFS

load_dotenv(".env.development")

config = DiscordConfig(token=os.environ["DISCORD_BOT_TOKEN"])
vfs = DiscordVFS(config=config)


async def main():
    ws = Workspace({"/discord": vfs}, mode=MountMode.READ)

    # List guilds
    r = await ws.shell("ls /discord/")
    print(await r.stdout_str())

    guild = (await r.stdout_str()).strip().splitlines()[0]

    # List channels
    r = await ws.shell(f'ls "/discord/{guild}/channels/"')
    print(await r.stdout_str())

    ch = (await r.stdout_str()).strip().splitlines()[0]
    base = f"/discord/{guild}/channels/{ch}"

    # Discover an available day, then read a few messages
    r = await ws.shell(f'ls "{base}/" | tail -n 1')
    day = (await r.stdout_str()).strip()
    r = await ws.shell(f'head -n 3 "{base}/{day}/chat.jsonl"')
    print(await r.stdout_str())

    # Extract usernames with jq
    r = await ws.shell(
        f'jq -r ".author.username" "{base}/{day}/chat.jsonl"')
    print(await r.stdout_str())

    # Count messages per user
    r = await ws.shell(
        f'cat "{base}/{day}/chat.jsonl"'
        ' | jq -r ".author.username" | sort | uniq -c')
    print(await r.stdout_str())

    # List attachments for a day
    r = await ws.shell(f'ls "{base}/{day}/files/"')
    print(await r.stdout_str())

    # Search every day of the channel
    r = await ws.shell(f'grep -r hello "{base}/"')
    print(await r.stdout_str())

    # Search across the guild
    r = await ws.shell(f'grep -r hello "/discord/{guild}/"')
    print(await r.stdout_str())

    # Navigate with cd/pwd
    await ws.shell(f'cd "{base}"')
    r = await ws.shell("pwd")
    print(await r.stdout_str())

    # Relative paths after cd
    r = await ws.shell("ls | tail -n 5")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

See examples/python/vfs/discord/discord.py for the full working example.

Finding IDs

VFS-specific commands require Discord snowflake IDs (channel_id, guild_id, message_id). These can be extracted from the filesystem:

# Guild ID - use stat
stat "/discord/My Server__111222333444555666"
# → extra={"guild_id": "1256522563555819574"}

# Channel ID - use stat
stat "/discord/My Server__111222333444555666/channels/general__777888999000111222"
# → extra={"channel_id": "1256522563555819574"}

# Message ID - inside JSONL messages
jq -r '"\(.id) [\(.author.username)] \(.content)"' \
  "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl"
# → 1489887688978075769 [alice] hello world

# Find a message then reply
jq -r 'select(.content | test("hello")) | .id' \
  "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl"
# → 1489887688978075769
discord send --channel 1256522563555819574 \
  --text "Reply" --reply-to 1489887688978075769

Working with Large Channels

Tips for efficient access on busy channels:

# Check message count per day
wc -l "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl"

# Read only recent messages
tail -n 10 "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl"

# Search one day
grep "keyword" "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl"

# Extract specific fields
jq -r '"\(.author.username): \(.content)"' \
  "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl" | head -n 20

# Count messages per user
cat "/discord/My Server__111222333444555666/channels/general__777888999000111222/2026-04-04/chat.jsonl" \
  | jq -r '.author.username' | sort | uniq -c

Shell Commands

Standard commands available on the mounted Discord tree:

Command	Notes
`ls`	List guilds, channels, members, dates, attachments
`cat`	Read `chat.jsonl`, member `.json`, or download an attachment
`head` / `tail`	Smart: uses messages API for file scope
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON; runs once per line of a JSONL file (`-s` for all)
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type, ID via `extra`)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view

Acting on Discord (sending, editing, reactions, threads, polls, member and guild info, search) goes through the discord CLI when installed; the mounted tree stays read-oriented. The <name>__<id> path segments supply the snowflake IDs the CLI flags take.

Time scope

Set start_time and/or end_time in the mount’s YAML config (or pass start_time/end_time to Python; startTime/endTime to the TypeScript constructor). Bounds are RFC3339 timestamps with an explicit timezone and at most millisecond precision. Start is inclusive; end is exclusive. An omitted or null bound is open. Start must precede end.

mounts:
  /history:
    vfs: discord
    mode: read
    config:
      token: "<bot-token>"
      start_time: "2026-06-01T10:00:00Z"
      end_time: "2026-06-02T00:00:00Z"

With a bound configured, channel listings cover the selected period rather than the default recent window. Day directories use UTC. Messages are selected by creation time, and attachments follow their parent messages. Direct paths, stat, date globs, and grep/rg cannot escape the scope. Scoped searches scan the filtered files. User/member and channel/server metadata remain visible as context. These settings apply to the VFS, not to separately installed account CLIs. mode: read prevents mount writes; it does not freeze upstream edits or deletions. Rebuild/remount the VFS to change its scope so cached listings and bytes are cleared.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Guilds

Channels

Members

Smart Commands

grep / rg

head / tail

Cache

Integration

Example

Finding IDs

Working with Large Channels

Shell Commands

Time scope

​Config

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Guilds

​Channels

​Members

​Smart Commands

​grep / rg

​head / tail

​Cache

​Integration

​Example

​Finding IDs

​Working with Large Channels

​Shell Commands

​Time scope

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Guilds

Channels

Members

Smart Commands

grep / rg

head / tail

Cache

Integration

Example

Finding IDs

Working with Large Channels

Shell Commands

Time scope