Skip to main content
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.
On the SSH port only public keys log in: no passwords. Nothing is forwarded: no ports, no agent, no X11. To reach a server through its HTTPS port instead, with the CLI’s token and no key, see Over HTTPS.

​
Turn it on

1

Install the SSH library

2

Pick a port

SSH stays off until a port is set.
3

Authorize your key

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

Restart and connect

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.

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

​
Bind a key to an account

The mirage-account option makes the key belong to that account: it opens only the workspaces the account created. Shell, exec, sftp and scp are all held to it.
~/.mirage/ssh/authorized_keys
Another account’s workspace answers like a missing one. In jwt mode a key without the option opens nothing; in local and token mode it opens every workspace. An option that is empty or given twice opens nothing.

​
Over HTTPS

The server also carries SSH over its HTTP port, at /v1/workspaces/{id}/ssh, so a hosted server needs no second port open. mirage ssh-proxy <id> relays it on stdio, which makes it ssh’s ProxyCommand:
Or once, in your SSH config:
~/.ssh/config
Then ssh demo@mirage, sftp demo@mirage, scp notes.txt demo@mirage:/data/ and sshfs -o direct_io demo@mirage:/ ~/mnt/demo all work, with no key and no ssh_port. The CLI reaches the server its url names, or the one it starts on your machine, and sends its token: on a hosted server, the one mirage login keeps. The route checks that token like any HTTP request, so in jwt mode the login is the token’s account and reaches only its workspaces. The login may only name the workspace in the route, and runs under the workspace’s default profile. The server still needs the SSH library from Turn it on.

​
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. The server sends a keepalive every 15 seconds and closes a connection that misses three, so a half-open one cancels its line as well.