SSH

The SSH VFS mounts a remote server’s filesystem over SFTP. It supports full read and write operations. Install the extra:

pip install "mirage-ai[ssh]"

Config

from mirage import MountMode, Workspace
from mirage.vfs.ssh import SSHConfig, SSHVFS

config = SSHConfig(
    host="myserver",
    username="deploy",
    identity_file="~/.ssh/id_ed25519",
    root="/var/data",
)
vfs = SSHVFS(config=config)
ws = Workspace({"/remote": vfs}, mode=MountMode.WRITE)

Field	Description
`host` required	Host name, IP address or `~/.ssh/config` alias of the remote.
`hostname`	Address to connect to instead of `host`.
`port`	SSH port; unset uses the client’s default, `22` unless `~/.ssh/config` sets one for the host.
`username`	Login user; unset uses the local user name unless `~/.ssh/config` sets one for the host.
`identity_file`	Path to a private key; `~` is expanded. Unset tries the SSH agent and the default keys in `~/.ssh`.
`password` secret	Password for password authentication; prefer `identity_file`.
`passphrase` secret	Passphrase of an encrypted `identity_file`; ignored when `identity_file` is unset.
`root` default `'/'`	Path on the remote that becomes the mount root.
`timeout` default `30`	Seconds to wait for the TCP connection, and again for authentication.
`known_hosts`	Path to a `known_hosts` file the server’s host key is checked against; unset disables host-key checking.

Fields marked secret are redacted in snapshots. The host field matches entries in ~/.ssh/config, so existing SSH configurations are automatically picked up.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`ssh`, write

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>`	Almost all Unix commands. `grep -r` and `rg` ask `ssh` which files may match. `wc -l` asks `ssh` instead of reading a file.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`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>` | `ssh`, write |

## 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>` | Almost all Unix commands. `grep -r` and `rg` ask `ssh` which files may match. `wc -l` asks `ssh` instead of reading a file. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `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.

/remote/
  <remote-directory-tree>

The mounted tree mirrors the remote filesystem starting at root. Example with root="/var/data":

/remote/
  logs/
    app.log
    nginx/
      access.log
      error.log
  config/
    app.yaml
  uploads/
    image.png

Cache

Directory listings are cached for 60 seconds by default (a configured index: uses its own ttl, and the mount’s ttl: caps it). File bytes are cached and served without a check until the mount’s ttl:; SSH does not accept read: fresh.

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.vfs.ssh import SSHConfig, SSHVFS

config = SSHConfig(
    host="myserver",
    username="deploy",
    identity_file="~/.ssh/id_ed25519",
    root="/var/log",
)
vfs = SSHVFS(config=config)


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

    # List remote directory
    r = await ws.shell("ls /logs/")
    print(await r.stdout_str())

    # Read last 20 lines of a log
    r = await ws.shell("tail -n 20 /logs/nginx/access.log")
    print(await r.stdout_str())

    # Search across log files
    r = await ws.shell('grep "ERROR" /logs/app.log')
    print(await r.stdout_str())

    # Find large files
    r = await ws.shell("find /logs/ -name '*.log'")
    print(await r.stdout_str())

    # File metadata
    r = await ws.shell("stat /logs/app.log")
    print(await r.stdout_str())


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

Integration

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

Command	On SSH
`grep -r`, `rg`	`grep` on the server, for any text. It misses nothing.
`wc -l`	`wc -l` on the server
`tail -f`	`tail -f` on the server
`md5sum`, `sha256sum` and the other hash commands	The matching sum tool on the server
`find`, `du`, `ls -R`, `tree`	One `find` on the server

grep -r and rg run grep on the server to find which files hold the text, then read only those. The answer is exact. Every file is read when the server runs no commands (an SFTP-only account), its grep refuses an option (busybox), or it cannot read a file.

Shell Commands

Command	Notes
`ls`	List remote files and directories
`cat`	Read remote file content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search; `-r` asks the server’s grep which files to read
`wc`	Line/word/byte counts
`stat`	File metadata (size, mtime)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`mkdir`	Create remote directories
`touch`	Create empty remote files
`cp` / `mv` / `rm`	Copy, move, delete on remote
`tee`	Write stdin to remote file
`diff` / `cmp`	Compare remote files
`sort` / `cut` / `tr`	Text processing
`tar` / `zip` / `gzip`	Compression

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example

Integration

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Cache

​Example

​Integration

​Shell Commands

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example

Integration

Shell Commands