Set up
1
Install the SSH library
- Python
- TypeScript
2
Pick a port
3
Authorize your key
4
Restart the server
Settings
Settings
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
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.- FastAPI
- Express
app.py
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)
Inlocal 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:
Account rules in detail
Account rules in detail
- The account holds for shell, exec,
sftpandscpalike. - In
localandtokenmode, a key withoutmirage-accountopens every workspace. - An option that is empty or given twice opens nothing.
How sessions behave
How sessions behave
- Each
ssh,sftporscprun 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 ignoresSIGHUPkeeps running, and on Linux so does one that left the line’s session withsetsid. - 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.1orlocalhostonly, where the session’s lines run (Editors). Agents and X11 are never forwarded.