SSH

SSHVFS opens an SFTP session and mounts the remote root as a filesystem.

Node only. Requires the ssh2 peer dependency. The browser SDK doesn’t ship an SSH client.

Install

pnpm add @struktoai/mirage-node ssh2

Config

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

const ssh = new SSHVFS({
  host: 'jump.example.com',
  username: 'me',
  identityFile: '~/.ssh/id_ed25519',
  root: '/srv/data',
})

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

Field	Description
`host` required	DNS name or IP address of the remote.
`hostname`	Address to connect to instead of `host`.
`port` default `22`	SSH port.
`username`	Login user; unset uses the local user name.
`password` secret	Password for password authentication; prefer `identityFile`.
`identityFile`	Path to a private key; `~` is expanded. Unset tries the SSH agent and the default keys in `~/.ssh` (`id_ed25519`, `id_ecdsa`, `id_rsa`, `id_dsa`).
`passphrase` secret	Passphrase of an encrypted private key, from `identityFile` or a default key.
`root` default `'/'`	Path on the remote that becomes the mount root.
`timeout` default `30`	Seconds to wait for the connection to be ready, authentication included.
`knownHosts`	Accepted but not applied: this backend does not verify host keys.

Fields marked secret are redacted in snapshots.

Mount mode

read, write, exec. Writes flush via SFTP put. Use MountMode.EXEC if python3 or js should run scripts from the mount. For the full set of supported shell commands see the Python SSH docs.

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.

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

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Install

Config

Mount mode

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Install

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Install

Config

Mount mode

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration