SSH

The Mirage server can listen for SSH next to HTTP. The SSH username names the workspace. Every line runs in Mirage’s shell, and every file operation goes through the workspace’s mounts.

ssh -p 2222 demo@127.0.0.1                     # a shell in workspace "demo"
ssh -p 2222 demo@127.0.0.1 'ls /data | wc -l'  # one line
ssh -T -p 2222 demo@127.0.0.1 < setup.sh       # a script
sftp -P 2222 demo@127.0.0.1                    # file transfer
scp -P 2222 notes.txt demo@127.0.0.1:/data/    # copy in

Only public keys log in: no passwords. Nothing is forwarded: no ports, no agent, no X11.

Turn it on

Install the SSH library

pip install 'mirage-ai[ssh]'

npm install -g ssh2

Pick a port

mirage config set ssh_port 2222

SSH stays off until a port is set.

Authorize your key

mkdir -p ~/.mirage/ssh
cat ~/.ssh/id_ed25519.pub >> ~/.mirage/ssh/authorized_keys

The file is read on every login, so adding or removing a key needs no restart.

Restart and connect

mirage daemon restart
mirage workspace create workspace.yaml --id demo
ssh -p 2222 demo@127.0.0.1

The server makes its host key on first start and keeps it, so your known_hosts entry stays valid.

Settings

An environment variable wins over ~/.mirage/config.toml, which wins over the default.

Key	Env var	Default
`ssh_port`	`MIRAGE_SSH_PORT`	unset (off)
`ssh_host`	`MIRAGE_SSH_HOST`	`127.0.0.1`
`ssh_host_key_file`	`MIRAGE_SSH_HOST_KEY_FILE`	`~/.mirage/ssh/host_ed25519_key`
`ssh_authorized_keys`	`MIRAGE_SSH_AUTHORIZED_KEYS`	`~/.mirage/ssh/authorized_keys`

Bind a key to a profile

The mirage-profile option runs every login of that key under a profile. A key without it gets the workspace’s default.

~/.mirage/ssh/authorized_keys

mirage-profile="guarded" ssh-ed25519 AAAA... agent-a
ssh-ed25519 AAAA... me

The server reads the option, not the client, so a key cannot pick looser rules. Give each agent’s sandbox its own key, bound to that agent’s profile.

Sessions

Each channel (one ssh, sftp or scp run) gets a fresh session, closed when it ends, so a cd or export never leaks between them. The session’s profile and the mount modes apply as in any shell: a read-only mount refuses sftp put. Ctrl-C cancels the running line and sets $? to 130, a dropped connection cancels it too, and ssh host cmd exits with the line’s status.

Getting Started

Access

Learn

Help

VFS

CLIs

Runtimes

Turn it on

Settings

Bind a key to a profile

Sessions

​Turn it on

​Settings

​Bind a key to a profile

​Sessions

Turn it on

Settings

Bind a key to a profile

Sessions