SSH

The ssh machine provider reaches a machine running sshd, and the machine runtime runs captured programs 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

Python
TypeScript

pip install 'mirage-ai[ssh]'

pnpm add ssh2

Usage

captures defaults to @external: every program Mirage does not have itself. Name @python to run Python on the machine too.

Python
TypeScript
YAML

from mirage import RAMVFS, MountMode, Workspace
from mirage.runtime.machine import MachineRuntime

ws = Workspace(
    {"/data": RAMVFS()},
    mode=MountMode.EXEC,
    machines={
        "box": {
            "provider": "ssh",
            "host": "mybox",
            "username": "deploy",
            "identity_file": "~/.ssh/id_ed25519",
        }
    },
    runtimes=[MachineRuntime(["@python", "@external"], machine="box")],
)
await ws.shell("python3 -c 'print(1 + 1)'")

import { MountMode, MachineRuntime, 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',
      },
    },
    runtimes: [new MachineRuntime({ captures: ['@python', '@external'], machine: 'box' })],
  },
)
await ws.shell("python3 -c 'print(1 + 1)'")

mode: exec
machines:
  box:
    provider: ssh
    host: mybox
    username: deploy
    identity_file: ~/.ssh/id_ed25519
runtimes:
  - name: machine
    captures: ["@python", "@external"]
    machine: box
mounts:
  /data:
    vfs: ram

Connecting the workspace

A program on the machine opens workspace files at the same paths as in Mirage, so the machine must see the mounts there. With mount_type: ssh, Mirage serves every mount over the runtime’s own connection and the machine mounts each with sshfs, as for Docker. The machine needs sshfs, and passwordless sudo for a mountpoint its user cannot create (/data). Without mount_type, two ways: Files already on the machine. Mount the machine’s directory with the ssh VFS at a prefix equal to its path there. The same path then names the same file on both sides, with nothing to install:

mounts:
  /home/user/proj:
    vfs: ssh
    config:
      host: mybox
      root: /home/user/proj
machines:
  box:
    provider: ssh
    host: mybox
runtimes:
  - name: machine
    captures: ["@python", "@external"]
    machine: box

Any other mount (S3, Slack and so on). Install Mirage and fuse3 on the machine. Write the same mounts at the same paths into sandbox.yaml, and start Mirage with it there:

mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
    backend: fuse
    mountpoint: /data

ssh mybox mirage workspace create sandbox.yaml

Nothing checks that the paths match; a mismatch shows only when a program misses a file. For a friendlier name, put or link the directory at that path on the machine: Mirage never rewrites paths. A program on the machine opens its files directly, outside this workspace’s mount modes and permissions.

Runtime behavior

Capability	On the machine
Command	The captured program and its words, as typed
Piped input	stdin
Environment	The session’s, over the config `env`
Working directory	The shell’s, unchanged
Workspace files	The machine’s own paths; see above
Disk and network	The machine’s own

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

Host keys are not verified, so treat the network path to the machine as trusted.

Getting Started

Examples

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Machines

Infrastructure

Configuration

Notifications

Help

Installation

Usage

Connecting the workspace

Runtime behavior

Notes

​Installation

​Usage

​Connecting the workspace

​Runtime behavior

​Notes

Installation

Usage

Connecting the workspace

Runtime behavior

Notes