Quickstart
This page uses an installation that already exists. To make one, see Install on AWS; to try Spinbox on one Linux machine without one, see Try it on one machine.
You need the address of the installation’s dashboard, https://app.<domain>, and an account
on it. Ask whoever runs it, or sign in with the first administrator’s account if you installed
it.
1. Get the CLI
Section titled “1. Get the CLI”The CLI is a single binary, published with every release as spin-linux-amd64,
spin-linux-arm64, spin-darwin-arm64 and spin-darwin-amd64. Put the one for your machine on
your PATH as spin:
chmod +x spin-linux-amd64sudo mv spin-linux-amd64 /usr/local/bin/spinspin versionEach is also in the release’s public package, under a tag of its own:
oras pull ghcr.io/spin-stack/spin-release:v20261027.01-spin-linux-amd642. Sign in
Section titled “2. Sign in”spin login --endpoint https://app.<domain>The CLI prints a page’s address and a code, and opens the page in your browser where it can. Sign
in there, from this machine or any other, enter the code, and the CLI is signed in. spin whoami shows who you are, and spin smoke checks the installation does
what this page expects, with a workspace of its own that it erases.
3. Create a workspace
Section titled “3. Create a workspace”spin workspace create --name demo --waitThe workspace starts from the installation’s default image, with its default CPU, memory and
disk. If no runner is up, it waits in Waiting for a host for the few minutes one takes to
start; --wait waits for it.
A workspace lets you in with an SSH key you added with your passkey. Add one once, from this machine: the command opens the page where your passkey confirms it, and waits. See Who gets into your workspaces.
spin ssh-key add laptop ~/.ssh/id_ed25519.pubspin workspace listspin ssh demoYou are root inside a virtual machine of your own, running Ubuntu.
A workspace reaches only what its network policies allow, and by default that can be nothing at all. To see which policies the installation has, and to create a workspace that can reach what one of them allows:
spin workspace policiesspin workspace create --name online --network-tag <policy> --waitSee Network and egress.
4. Take a snapshot
Section titled “4. Take a snapshot”Back on your machine:
spin snapshot create demo --description "clean" --waitspin snapshot list demoA snapshot is a point to come back to. Add --with-memory to keep the running processes too.
5. Change something, and see what changed
Section titled “5. Change something, and see what changed”spin exec demo -- sh -c 'echo hello > /etc/greeting; rm /etc/issue; echo "# edited" >> /etc/hosts'spin snapshot create demo --description "after" --waitspin snapshot diff demo <after-id> --from <clean-id> --under /etcThe diff lists every file added (A), removed (D), modified (M) or changed type (T)
between the two snapshots: here, /etc/greeting added, /etc/issue removed and /etc/hosts
modified. It runs in a separate machine, so the workspace does not need to be running.
--under narrows it to one directory; installing a package alone changes thousands of files.
6. Go back
Section titled “6. Go back”A disk restore needs the workspace stopped:
spin workspace stop demo --waitspin workspace restore demo <clean-id>spin workspace start demo --waitThe disk is back to the snapshot. Anything written after the snapshot is given up, unless a
snapshot was taken after it: the after snapshot is still there, so
spin workspace restore demo <after-id> undoes this restore. What the disk wrote after its last
snapshot is lost.
To go back with the processes as they were, take the snapshot with --with-memory, then:
spin workspace restore demo <snapshot-id> --with-memory7. Open a port
Section titled “7. Open a port”Start a web server in the workspace and expose its port:
spin exec demo -- sh -c 'nohup sh -c "while true; do printf \"HTTP/1.0 200 OK\r\n\r\nhello\n\" | nc -l 8000; done" >/dev/null 2>&1 &'spin port expose demo 8000It is at https://8000-demo.ws.<domain>, and only you can open it. See
Ports and sharing to let others in.
8. Clean up
Section titled “8. Clean up”spin workspace delete demoWhere the installation keeps a trash, the workspace goes there with its disk, and
spin workspace undelete demo brings it back; --permanently erases it now.
- Workspaces and Snapshots and rollback
- Editors and SSH: VS Code,
ssh,scpandrsync - Agents and automation: API keys and JSON output
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

