Skip to content
Spinbox is experimental: APIs change and data may be lost. Status lists what is built and what proves it.

Editors and SSH

View Markdown

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

Everything below - spin ssh, plain ssh, spin exec, VS Code - logs in with an SSH key you added once, with your passkey:

Terminal window
spin ssh-key add laptop ~/.ssh/id_ed25519.pub

Who gets into your workspaces says what a passkey is for, which keys log in, and how a guest is let in.

Terminal window
spin ssh api
spin ssh api --start # start it first if it is stopped
spin ssh api -- -L 8080:localhost:80 # anything after -- goes to ssh

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

Terminal window
spin ssh-config
ssh spin.api
scp ./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.

Terminal window
spin code api
spin code api /srv/app --start

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

A workspace’s page in the dashboard has Open terminal, a shell in the browser, over the same relay.

Terminal window
spin exec api -- make test
spin exec api -w /srv/app -- git status
spin exec api -- cat build.log > local.log

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

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.