Email

EmailVFS reads the mailbox over IMAP as a tree of folders and messages. The himalaya CLI sends mail.

Node only. Requires imapflow, mailparser, and nodemailer peers. The browser cannot speak raw TCP for IMAP/SMTP.

Install

pnpm add @struktoai/mirage-node imapflow mailparser nodemailer

Config

import { EmailVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const email = new EmailVFS({
  imapHost: 'imap.example.com',
  smtpHost: 'smtp.example.com',
  username: process.env.EMAIL_USERNAME!,
  password: process.env.EMAIL_PASSWORD!,
})

const ws = new Workspace({ '/mail': email }, { mode: MountMode.READ })
await ws.shell('ls /mail/INBOX/')

Field	Description
`timeout` 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.
`imapHost` required	IMAP server hostname.
`imapPort` default `993`	IMAP server port.
`smtpHost` required	SMTP server hostname `himalaya` sends mail through.
`smtpPort` 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`.
`useSsl` default `true`	Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows `smtpPort` instead.
`maxMessages` 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.
`saveCopy` default `true`	After `himalaya` sends a message, append a copy to `sentFolder`, as upstream himalaya’s `message.send.save-copy`. Off saves a copy only when `--save` names a mailbox.
`sentFolder` default `null`	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.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  <folder>/                         # INBOX, Sent, Drafts, ...
    <yyyy-mm-dd>/
      <subject>__<uid>.email.json   # the message as JSON
      <subject>__<uid>/             # its attachments, if any
        <attachment-filename>

<subject> is sanitized: ls the date directory rather than construct it.
To list, search, read, compose, reply or 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 |

## VFS Layout

### `/<path>`

```text
/<path>
  <folder>/                         # INBOX, Sent, Drafts, ...
    <yyyy-mm-dd>/
      <subject>__<uid>.email.json   # the message as JSON
      <subject>__<uid>/             # its attachments, if any
        <attachment-filename>
```

- `<subject>` is sanitized: `ls` the date directory rather than
  construct it.
- To list, search, read, compose, reply or 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.

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).

The Python Email docs list when each search answers and what it can miss.

Mount mode

read. Send mail through the himalaya CLI. For mailbox layout, search behavior, and synthesized date directories see the Python Email docs.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Install

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Mount mode

​Install

​Config

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

​Mount mode

Install

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Mount mode