Editors and SSH
Every way into a workspace goes through the installation’s relay. You never need network access
to the runner or to the workspace, only to https://app.<domain>.
A key that logs in as you
Section titled “A key that logs in as you”Everything below - spin ssh, plain ssh, spin exec, VS Code - logs in with an SSH key you
added once, with your passkey:
spin ssh-key add laptop ~/.ssh/id_ed25519.pubWho gets into your workspaces says what a passkey is for, which keys log in, and how a guest is let in.
spin ssh
Section titled “spin ssh”spin ssh apispin ssh api --start # start it first if it is stoppedspin ssh api -- -L 8080:localhost:80 # anything after -- goes to sshYou are root. The CLI carries the connection over a WebSocket to the relay, and SSH itself
stays end to end between your client and the workspace’s sshd.
It runs your own ssh, which has to be OpenSSH 9.9 or newer: a workspace accepts only the
post-quantum key exchange mlkem768x25519-sha256, so spin ssh, spin ssh-config and
spin code check your ssh first and refuse an older one before asking anything of the
workspace.
Plain ssh, scp and rsync
Section titled “Plain ssh, scp and rsync”spin ssh-configssh spin.apiscp ./notes.txt spin.api:/root/rsync -a ./src/ spin.api:/root/src/spin ssh-config writes ~/.spin/ssh/config, with that key exchange in its block, and includes
it from ~/.ssh/config; for an older ssh it writes nothing, since one would refuse the whole
file over that line. From then on,
any program that runs ssh reaches a workspace as the host spin.<workspace>. Each connection
gets a new certificate for your key that is valid for five minutes, so a certificate that leaks
is useless minutes later; what lasts is the key itself, which stays on your machine.
It uses the key you name with -i, or the first key this machine holds that you have added:
~/.ssh’s, a FIDO2 key’s among them, then ssh-agent’s. If the machine has none, the CLI makes
one of its own and says how to add it. The private half never leaves your machine: the control
plane signs a short certificate for the public half, per connection.
VS Code
Section titled “VS Code”spin code apispin code api /srv/app --startThis opens VS Code with Remote-SSH at the path you name: by default the project’s checkout,
/workspace/<repository>, or /workspace in a workspace with no project. It needs the code
command and the Remote-SSH extension; --editor names another editor’s command.
VS Code runs a server in the workspace, built for its own commit. An installation’s servers
reach a workspace on a read-only disk its host attaches, and ~/.vscode-server on the
workspace’s disk holds only links into it, so nothing is downloaded when you connect. No image
carries a server: an administrator publishes them from Admin → Storage.
Before VS Code connects, spin code asks the workspace whether it has the server for your
VS Code. If it has not, and the installation has published that version, the running workspace
is given it. If the installation has not, it prepares that version first, once for the whole
installation, where an administrator has accepted the server’s terms (Admin → Extensions).
Otherwise VS Code downloads its own server into the workspace, about 220 MB, and spin code
says so before connecting; where the workspace has no room for that download, it refuses and
says what would free it.
The server is Microsoft’s, and its licence allows it for an organization’s own internal use only. An installation that offers workspaces to others must not carry it: it leaves VS Code to download its own, under a licence each user accepts.
Any editor with a remote-over-SSH mode works the same way through spin ssh-config.
The dashboard’s terminal
Section titled “The dashboard’s terminal”A workspace’s page in the dashboard has Open terminal, a shell in the browser, over the same relay.
Running one command
Section titled “Running one command”spin exec api -- make testspin exec api -w /srv/app -- git statusspin exec api -- cat build.log > local.logspin exec runs a command in the workspace, connects its standard input, output and error to
yours, and exits with its exit status. It allocates a terminal only when both ends are one, so
its output is safe to pipe.
Letting someone else in
Section titled “Letting someone else in”spin workspace guests add lets a person into a workspace of yours, with a key of their own:
see Sharing a workspace.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

