Email

The Email VFS exposes any IMAP mailbox as a virtual filesystem mounted at some prefix such as /email/. Sending is handled via SMTP. Sending through himalaya needs the extra:

pip install "mirage-ai[email]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.email import EmailConfig, EmailVFS

config = EmailConfig(
    imap_host=os.environ["IMAP_HOST"],
    smtp_host=os.environ["SMTP_HOST"],
    username=os.environ["EMAIL_USERNAME"],
    password=os.environ["EMAIL_PASSWORD"],
)
vfs = EmailVFS(config=config)
ws = Workspace({"/email": vfs}, mode=MountMode.READ)

Config Reference

Field	Description
`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.
`imap_host` required	IMAP server hostname.
`imap_port` default `993`	IMAP server port.
`smtp_host` required	SMTP server hostname `himalaya` sends mail through.
`smtp_port` default `587`	SMTP server port. `465` uses implicit TLS; any other port starts in plaintext and upgrades with STARTTLS when the server offers it.
`username` required	Login for both IMAP and SMTP, usually the email address.
`password` required, secret	Password or app password for `username`.
`use_ssl` default `True`	Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows `smtp_port` instead.
`max_messages` default `200`	How many of a folder’s newest messages the mount lists and `grep` searches, and the window `himalaya envelope list` and `search` page through.
`save_copy` default `True`	After `himalaya` sends a message, append a copy to `sent_folder`, as upstream himalaya’s `message.send.save-copy`. Off saves a copy only when `--save` names a mailbox.
`sent_folder`	Mailbox a sent copy goes to. Unset asks the server for the mailbox tagged `\Sent` and falls back to `Sent`.

Fields marked secret are redacted in snapshots.

Common VFS Settings

Provider	IMAP Host	SMTP Host	Notes
Yahoo	`imap.mail.yahoo.com`	`smtp.mail.yahoo.com`	App password required
Fastmail	`imap.fastmail.com`	`smtp.fastmail.com`	App password
iCloud	`imap.mail.me.com`	`smtp.mail.me.com`	App password
ProtonMail	`127.0.0.1` (Bridge)	`127.0.0.1` (Bridge)	Requires ProtonMail Bridge
Self-hosted	Your server hostname	Your server hostname	Whatever you configured

For credentials and provider support, see Email setup.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

`/<path>` layout

/<path>
  <folder>/
    <yyyy-mm-dd>/
      <subject>__<uid>.email.json
      <subject>__<uid>/           # if attachments exist
        <attachment-filename>
  Folders include: INBOX, Sent, Drafts, etc. cat shows email as JSON.

  <subject> is sanitized (don't construct it; ls the date dir).

  To act on mail (list/search/read/compose/reply/forward), use the
  himalaya CLI if installed: himalaya --help

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). `grep -r` and `rg` ask `email` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `email` answers only for `//*.email.json`; `grep -r` and `rg` read every other file. `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>` | `email`, read |

## `/<path>` layout

```text
/<path>
  <folder>/
    <yyyy-mm-dd>/
      <subject>__<uid>.email.json
      <subject>__<uid>/           # if attachments exist
        <attachment-filename>
  Folders include: INBOX, Sent, Drafts, etc. cat shows email as JSON.

  <subject> is sanitized (don't construct it; ls the date dir).

  To act on mail (list/search/read/compose/reply/forward), use the
  himalaya CLI if installed: himalaya --help
```

## 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). `grep -r` and `rg` ask `email` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `email` answers only for `*/*/*.email.json`; `grep -r` and `rg` read every other file. `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.

/email/
  <folder>/
    <yyyy-mm-dd>/
      <sanitized-subject>__<uid>.email.json
      <sanitized-subject>__<uid>/   # only if message has attachments
        <attachment-filename>

Example:

/email/
  INBOX/
    2026-04-14/
      Meeting_Notes__12345.email.json
      Meeting_Notes__12345/
        report.pdf
        screenshot.png
      Simple_Email__12346.email.json
    2026-04-13/
      Hello__12347.email.json
  Sent/
    2026-04-14/
      Reply__12348.email.json
  Drafts/
  Archive/

Folder directories appear at the root, using IMAP folder names (e.g., INBOX, Sent, Drafts).

Date Directories

Inside each folder, messages are grouped into date subdirectories formatted as YYYY-MM-DD. The date is derived from the message’s Date header.

Message Files

Each message is stored as a .email.json file. The filename shape is:

<sanitized-subject>__<uid>.email.json

Attachments

Messages that have attachments get a companion subdirectory with the same base name (without .email.json):

Meeting_Notes__12345.email.json    # message JSON
Meeting_Notes__12345/              # attachment directory
  report.pdf
  screenshot.png

Cache

The Email VFS uses IndexCacheStore (same as Gmail, Slack, Discord, and other mounts). Index entries store folder names, message UIDs, and message metadata.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.himalaya import HIMALAYA
from mirage.vfs.email import EmailConfig, EmailVFS

load_dotenv(".env.development")

config = EmailConfig(
    imap_host=os.environ["IMAP_HOST"],
    smtp_host=os.environ["SMTP_HOST"],
    username=os.environ["EMAIL_USERNAME"],
    password=os.environ["EMAIL_PASSWORD"],
)
vfs = EmailVFS(config=config)


async def main():
    ws = Workspace({"/email": vfs}, mode=MountMode.READ)
    ws.register_cli("himalaya", HIMALAYA, config.model_dump())

    # List folders
    r = await ws.shell("ls /email/")
    print(await r.stdout_str())

    # List date directories in INBOX
    r = await ws.shell("ls /email/INBOX/")
    print(await r.stdout_str())

    # List messages for a specific date
    r = await ws.shell("ls /email/INBOX/2026-04-14/")
    print(await r.stdout_str())

    # Read a message
    r = await ws.shell(
        "cat /email/INBOX/2026-04-14/Meeting_Notes__12345.email.json")
    print(await r.stdout_str())

    # Extract subject with jq
    r = await ws.shell(
        'jq ".subject"'
        " /email/INBOX/2026-04-14/Meeting_Notes__12345.email.json")
    print(await r.stdout_str())

    # List attachments
    r = await ws.shell("ls /email/INBOX/2026-04-14/Meeting_Notes__12345/")
    print(await r.stdout_str())

    # Search across all messages
    r = await ws.shell('rg "quarterly" /email/INBOX/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.shell("tree -L 2 /email/INBOX/")
    print(await r.stdout_str())

    # Triage unread messages
    r = await ws.shell(
        "himalaya envelope search -m INBOX --page-size 5 not flag seen")
    print(await r.stdout_str())

    # Send an email
    r = await ws.shell(
        'himalaya message compose --to "user@example.com"'
        ' --subject "Hello from MIRAGE"'
        ' --body "This email was sent via the MIRAGE email VFS." --send')
    print(await r.stdout_str())


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

Finding UIDs

VFS-specific commands require message UIDs. These can be extracted from the filesystem:

# UID is embedded in filename after "__"
ls /email/INBOX/2026-04-14/
# -> Meeting_Notes__12345.email.json   <- uid = 12345

# Read a message, then send a reply
himalaya message read -m INBOX 12345
himalaya message reply -m INBOX 12345 --body "Thanks for the notes" --send

For composing and sending mail, see the Himalaya CLI.

Shell Commands

Standard commands available on the mounted email tree:

Command	Notes
`ls`	List folders, dates, messages, attachments
`cat`	Read message JSON or attachment content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query message JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`basename`	Extract filename from path
`dirname`	Extract directory from path
`realpath`	Resolve path to absolute form
`nl`	Number lines of output

Acting on mail (list, read, send, reply, forward) goes through the himalaya CLI when installed.

Integration

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

Command	On Email
`grep -r`, `rg`	IMAP `SEARCH TEXT`, for any text. It can miss on a server that searches words rather than substrings (Dovecot with full-text search).

grep -r and rg read only the messages IMAP SEARCH TEXT names in each folder or day they walk (from the mount root, in every folder), and print what reading every message would. IMAP matches the headers and body in any case; each hit’s file is named from a header-only fetch. Attachments are always read. Every message is read when the text is a key of the message JSON or a flag name, holds anything but ASCII letters and spaces, matches more than max_messages messages in a folder, or the search fails. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since a server that answers SEARCH from a full-text index (Dovecot with an FTS plugin, for one) matches words rather than substrings, so a narrowed scan could miss a message there.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

Config Reference

Common VFS Settings

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Date Directories

Message Files

Attachments

Cache

Example

Finding UIDs

Shell Commands

Integration

​Config

​Config Reference

​Common VFS Settings

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Date Directories

​Message Files

​Attachments

​Cache

​Example

​Finding UIDs

​Shell Commands

​Integration

Config

Config Reference

Common VFS Settings

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Date Directories

Message Files

Attachments

Cache

Example

Finding UIDs

Shell Commands

Integration