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

Quickstart

View Markdown

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.

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:

Terminal window
chmod +x spin-linux-amd64
sudo mv spin-linux-amd64 /usr/local/bin/spin
spin version

Each is also in the release’s public package, under a tag of its own:

Terminal window
oras pull ghcr.io/spin-stack/spin-release:v20261027.01-spin-linux-amd64
Terminal window
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.

Terminal window
spin workspace create --name demo --wait

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

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

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

Terminal window
spin workspace policies
spin workspace create --name online --network-tag <policy> --wait

See Network and egress.

Back on your machine:

Terminal window
spin snapshot create demo --description "clean" --wait
spin snapshot list demo

A snapshot is a point to come back to. Add --with-memory to keep the running processes too.

Terminal window
spin exec demo -- sh -c 'echo hello > /etc/greeting; rm /etc/issue; echo "# edited" >> /etc/hosts'
spin snapshot create demo --description "after" --wait
spin snapshot diff demo <after-id> --from <clean-id> --under /etc

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

A disk restore needs the workspace stopped:

Terminal window
spin workspace stop demo --wait
spin workspace restore demo <clean-id>
spin workspace start demo --wait

The 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:

Terminal window
spin workspace restore demo <snapshot-id> --with-memory

Start a web server in the workspace and expose its port:

Terminal window
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 8000

It is at https://8000-demo.ws.<domain>, and only you can open it. See Ports and sharing to let others in.

Terminal window
spin workspace delete demo

Where the installation keeps a trash, the workspace goes there with its disk, and spin workspace undelete demo brings it back; --permanently erases it now.

Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.