> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH

> Virtualize a remote server's filesystem over SSH from Node.

`SSHVFS` mounts a directory of a remote server over SFTP: its folders and
files appear as they are on the server. Set up the key and server as in [SSH setup](https://docs.mirage.strukto.ai/home/setup/ssh.md). It ships in `@struktoai/mirage-node` only; the
browser package has no SSH client.

## Install

```bash theme={null}
npm install @struktoai/mirage-node ssh2
```

`ssh2` is a peer package that only this mount needs.

## Configure

```ts theme={null}
import { MountMode, SSHVFS, Workspace } from '@struktoai/mirage-node'

const ssh = new SSHVFS({
  host: 'server.example.com',
  username: 'deploy',
  identityFile: '~/.ssh/id_ed25519',
  root: '/srv/data',
})
const ws = new Workspace({ '/remote': ssh }, { mode: MountMode.WRITE })

const result = await ws.shell('ls /remote && tail -n 20 /remote/logs/app.log')
console.log(result.stdoutText)
await ws.close()
```

`hostname` connects to another address than `host`, and `port` to another
port. Use `MountMode.EXEC` when `python3` or `js` should run scripts from the
mount.

### Fields

**host** `string` *required*

DNS name or IP address of the remote.

**hostname** `string`

Address to connect to instead of `host`.

**port** `number` (default: 22)

SSH port.

**username** `string`

Login user; unset uses the local user name.

**password** `string`

Password for password authentication; prefer `identityFile`.

**identityFile** `string`

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

**privateKey** `string`

A private key's own text, such as one a credential pointer reads from a secret store; offered after `identityFile`'s.

**passphrase** `string`

Passphrase of an encrypted private key, from `identityFile`, `privateKey` or a default key.

**root** `string` (default: '/')

Path on the remote that becomes the mount root.

**timeout** `number` (default: 30)

Seconds to wait for the connection to be ready, authentication included.

**knownHosts** `string`

Accepted but not applied: this backend does not verify host keys.

Fields marked secret are redacted in snapshots.

## Authentication

The mount offers, in order, the key at `identityFile`, then the key text in
`privateKey`, which a [credential pointer](https://docs.mirage.strukto.ai/home/service-credentials.md#pointer-fields)
can read from a secret store. Without either, it tries the SSH agent and the
default keys in `~/.ssh`. `passphrase` unlocks an encrypted key. `password`
works too, but a key is preferred.

The server needs SFTP turned on. Reads and writes go as far as the SSH
account's own file permissions allow.

## Layout

```text theme={null}
/remote/
  logs/
    app.log
  reports/
    2026-11.csv
```

The tree mirrors the server from `root`: `/remote/logs/app.log` is
`/srv/data/logs/app.log` on the server.

## Behavior

* **Host keys:** not verified. `knownHosts` is accepted but not applied, so
  any host key is accepted.
* **Caching:** listings are cached for 60 seconds by default. File bytes are
  served from cache without a check until the mount's `ttl:`; an SSH mount
  does not accept `read: fresh`.
* **Running programs:** this mount reads and writes files. To run programs on
  the server, use the [SSH machine](https://docs.mirage.strukto.ai/home/setup/machine/ssh.md).

## Integration

SSH answers these commands on the server, so fewer files are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg`: `grep` on the server finds which files hold the text,
  then only those are read, so nothing is missed. 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.
* `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`: one `find` on the server.
* `du`: one `find` on the server.
* `ls -R` and `tree`: one `find` on the server.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with SSH mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `ssh`, `<mode>` |
>
> **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.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `ssh`, `<mode>` |
>
> ## 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.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.