> ## 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 Machine

> Run captured programs on any machine you can reach over SSH.

The `ssh` machine provider reaches a machine running `sshd`, and
runs the programs it captures on it. Anything you can
already `ssh` into works, with nothing to install on it. You run the
machine; Mirage only runs programs on it. Python SDK and Node.

## Installation

> [tab] Python
>
> ```bash theme={null}
> pip install 'mirage-ai[ssh]'
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add ssh2
> ```

## Usage

`captures` defaults to [`@external`](https://docs.mirage.strukto.ai/home/setup/machine/overview#captures):
every program Mirage does not have itself. Name `@python` to run
Python on the machine too.

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={
>         "box": {
>             "provider": "ssh",
>             "host": "mybox",
>             "username": "deploy",
>             "identity_file": "~/.ssh/id_ed25519",
>             "captures": ["@python", "@external"],
>         }
>     },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   {
>     mode: MountMode.EXEC,
>     machines: {
>       box: {
>         provider: 'ssh',
>         host: 'mybox',
>         username: 'deploy',
>         identityFile: '~/.ssh/id_ed25519',
>         captures: ['@python', '@external'],
>       },
>     },
>   },
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   box:
>     provider: ssh
>     host: mybox
>     username: deploy
>     identity_file: ~/.ssh/id_ed25519
>     captures: ["@python", "@external"]
> mounts:
>   /data:
>     vfs: ram
> ```

## Connecting the workspace

Pick a [`mount_type`](https://docs.mirage.strukto.ai/home/setup/machine/overview#connecting-the-workspace). With `ssh`, the machine needs `sshfs`, and
passwordless `sudo` for a mountpoint its user cannot create (`/data`).
With `mirage`, it needs `fuse3`, `uv` or `npm` to install
[`mirage-fuse`](https://docs.mirage.strukto.ai/home/setup/machine/overview#mirage), and the same `sudo`.
A Mac takes `mirage` alone, with macFUSE in place of `fuse3`
([A Mac](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#a-mac)).

Without `mount_type`, two ways:

**Files already on the machine.** Mount the machine's directory with the
[ssh VFS](https://docs.mirage.strukto.ai/python/vfs/ssh.md) at a prefix equal to its path there. The same
path then names the same file on both sides, with nothing to install:

```yaml theme={null}
mounts:
  /home/user/proj:
    vfs: ssh
    config:
      host: mybox
      root: /home/user/proj
machines:
  box:
    provider: ssh
    host: mybox
    captures: ["@python", "@external"]
```

**Any other mount** (S3, Slack and so on). Install Mirage and `fuse3` on the
machine, and start Mirage with a `sandbox.yaml` that lists the same paths:

```bash theme={null}
ssh mybox mirage workspace create sandbox.yaml
```

Mirage never rewrites paths and nothing checks that they match. A program on
the machine opens its files directly, outside this workspace's mount modes
and permissions.

## Notes

* `host` is also the address unless `hostname` overrides it; `port`,
  `username`, `identity_file`, `private_key` and `timeout` are optional.
  Authentication is a key or an agent, never a password.
* `private_key` takes the key's own text rather than a path, so a
  [credential pointer](https://docs.mirage.strukto.ai/home/service-credentials.md#pointer-fields) can read it
  from a secret store.
* The machine's login shell must be POSIX-compatible. Commands use the
  session's working directory and environment.

> [!WARNING]
>
> Host keys are not verified, so treat the network path to the machine as
> trusted.


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