> ## 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 directory over SFTP as files.

![](https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/python-logo.svg?fit=max\&auto=format\&n=F9Lv_nTaj6By6crk\&q=85\&s=cf5b268d330f7db46ea5cf6083f309a1)

Node.js

A directory on a remote server becomes a local-looking tree of files, read
and written over SFTP. It works from Python and Node.

## Setup

The server needs SFTP turned on and an SSH account with access to the
directory. Create a key and install it on the server, then check that SFTP
answers:

```bash theme={null}
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@server.example.com
sftp -i ~/.ssh/id_ed25519 deploy@server.example.com
```

* `private_key` takes the key's own text in place of `identity_file`'s path,
  so a [credential pointer](https://docs.mirage.strukto.ai/home/service-credentials.md#pointer-fields) can read
  it from a secret store.
* Without `identity_file` or `private_key`, the SSH agent and the default keys
  in `~/.ssh` are tried. `password` works too, but a key is preferred.

## Connect

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /remote:
>     vfs: ssh
>     mode: read
>     config:
>       host: server.example.com
>       username: deploy
>       identity_file: ~/.ssh/id_ed25519
>       root: /srv/data
> ```
>
> ```bash theme={null}
> mirage workspace create workspace.yaml --id remote
> mirage shell -w remote -c 'ls /remote'
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import MountMode, Workspace
> from mirage.vfs.ssh import SSHConfig, SSHVFS
>
> config = SSHConfig(
>     host="server.example.com",
>     username="deploy",
>     identity_file="~/.ssh/id_ed25519",
>     root="/srv/data",
> )
> ws = Workspace({"/remote": SSHVFS(config)}, mode=MountMode.READ)
> result = await ws.shell("ls /remote")
> print(await result.stdout_str())
> await ws.close()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, SSHVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   {
>     '/remote': new SSHVFS({
>       host: 'server.example.com',
>       username: 'deploy',
>       identityFile: '~/.ssh/id_ed25519',
>       root: '/srv/data',
>     }),
>   },
>   { mode: MountMode.READ },
> )
> const result = await ws.shell('ls /remote')
> console.log(result.stdoutText)
> await ws.close()
> ```

## Layout

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

* `/remote/logs/app.log` is `/srv/data/logs/app.log` on the server.
* In Python, `host` also matches a `~/.ssh/config` alias, and its settings
  apply.
* Host keys are checked only in Python with `known_hosts` set; the TypeScript
  VFS does not verify them.

## Sample runs

```bash theme={null}
$ ls /remote
logs
reports
```

```bash theme={null}
$ tail -n 2 /remote/logs/app.log
2026-11-16T09:14:02Z INFO request served path=/health
2026-11-16T09:14:05Z WARN slow query took=1.8s
```

```bash theme={null}
$ head -n 2 /remote/reports/2026-11.csv
day,orders
2026-11-01,412
```

`mode: write` allows changes, as far as the SSH account's permissions allow.
To run programs on the server, use the [SSH machine](https://docs.mirage.strukto.ai/home/setup/machine/ssh.md).

## SDK guides

> [card] [Python](https://docs.mirage.strukto.ai/python/vfs/ssh.md)
>
> Every config field, the VFS.md and write support.

> [card] [TypeScript](https://docs.mirage.strukto.ai/typescript/vfs/ssh.md)
>
> Every config field, the VFS.md and write support.


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