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.

Set up

1

Install the SSH library

2

Pick a port

SSH stays off until a port is set.
3

Authorize your key

Only public keys log in, and the file is read on every login.
4

Restart the server

An environment variable wins over ~/.mirage/config.toml, which wins over the default.The server makes its host key on first start and keeps it, so your known_hosts entry stays valid.

Connect

Each run gets a fresh session, so a cd or export never leaks between them. Ctrl-C cancels the running line, and ssh host cmd exits with the line’s status. To mount a folder on the machine running Mirage instead, use FUSE.

Over HTTPS

A hosted server carries SSH over its HTTPS port, so it needs no SSH port or key. mirage ssh-proxy relays it with the CLI’s token:
~/.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. The CLI sends its token, your mirage login on a hosted server, and the login runs under the workspace’s default profile.

In an app

A workspace a FastAPI or Express app holds takes SSH the same way: add it to a registry, under the name logins use, and start the SSH server next to the app.
app.py
To carry SSH over the app’s own port as well, mount build_app() in it, which serves the route mirage ssh-proxy reaches.

Editors

Cursor, VS Code and Antigravity open a workspace over SSH by installing their own server on a machine the workspace sends its lines to. Editors over SSH sets it up.

Auth (optional)

In local and token mode, an authorized key opens every workspace under the workspace’s default profile. Options in front of a key in authorized_keys narrow it:
~/.mirage/ssh/authorized_keys
On a jwt server, each login reaches only its account’s workspaces:
  • The account holds for shell, exec, sftp and scp alike.
  • In local and token mode, a key without mirage-account opens every workspace.
  • An option that is empty or given twice opens nothing.
  • Each ssh, sftp or scp run gets a fresh session, closed when it ends.
  • The session’s profile and the mount modes apply as in any shell: a read-only mount refuses sftp put.
  • Output streams as the line prints it.
  • Ctrl-C cancels the running line and sets $? to 130.
  • A dropped connection ends the line as sshd would. With a terminal it hangs the line up with SIGHUP. Without one (ssh -T, as editors connect), it sends nothing: the line runs on without input, and is hung up the first time it writes. On a machine, a process that ignores SIGHUP keeps running, and on Linux so does one that left the line’s session with setsid.
  • The server sends a keepalive every 15 seconds and closes a connection that misses three, so a half-open one hangs its line up as well.
  • A port forward reaches 127.0.0.1 or localhost only, where the session’s lines run (Editors). Agents and X11 are never forwarded.