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

What is Spinbox

View Markdown

Spinbox runs workspaces: virtual machines that a person or a program uses to run code. You install it in your own AWS account. It was built as a place to work, and what makes it a good one (a whole machine, snapshots, a network closed until you open it) is what makes it a place to run code you don’t fully trust, an agent’s included, and to see what that code changed and undo it.

Each workspace is its own QEMU/KVM machine. It has a kernel of its own, root access, a persistent disk and SSH. Its disk is cloned from an image, so creating a workspace does not download anything. Taking a snapshot seals the disk’s current layer, so it is fast.

  • Developers who want a remote machine per task. Open it in VS Code or over SSH. Stop it at the end of the day and its disk is still there the next morning.
  • Teams that run AI agents on real code. An agent gets the same whole machine a person does: it can install packages, run services, and break things. You take a snapshot before it starts, look at the diff when it finishes, and roll back if you do not like the result. The pieces made only for agents are built and tested, and the least used of all so far.
  • Platform and security teams who need that work to happen in their own account, on their own network, with egress they decide and logs they keep.
You want toSpinbox gives you
Start from a known stateA workspace cloned from an image or from any snapshot, without copying a disk
Keep a point to come back toA snapshot of the disk, or of the disk and memory together
UndoRestore the disk to a snapshot, or resume a memory snapshot with its processes
See what changedA file-by-file diff between two snapshots, computed in a separate machine
Control what code reachesNetwork policies: a workspace reaches nothing until a policy lets it
Reach a service insidehttps://<port>-<workspace>.ws.<your domain>, private to you until you share it
Hand work to an agentAPI keys with scopes, and a CLI that prints JSON

Each is a built feature, with what proves it on the status page: workspaces, snapshots and network. See Workspaces and Snapshots and rollback for the details.

No. Spinbox runs in your AWS account, installed by one OpenTofu module. See Install on AWS.

A small part runs all the time, and runners run only while workspaces do. See Cost.

Yes, on one Linux machine with KVM: Try it on one machine.

No. An installation is a handful of EC2 machines, buckets and roles that the module creates.

Status lists every feature with what proves it, says where a test can’t reach, and lists what is not built. Limitations lists what Spinbox does not do by design.

Privately, through a security advisory: see Reporting a vulnerability.

  • Parts that already exist. The disk is QEMU’s chain of qcow2 files, the network is Linux namespaces and nftables, the boot is a signed kernel and a verified root. Spinbox’s own code is mostly what joins them, which leaves less of it to be wrong.
  • A virtual machine, not a container. A container shares the host’s kernel with every other container. A workspace does not. Code that escapes a process still has to get out of a virtual machine, whose QEMU runs under its own user with almost nothing to reach. See Isolation.
  • Snapshots are layers, not copies. A disk is a chain of qcow2 layers. A snapshot seals the top one, a clone points at the same layers, and a diff compares two of them. None of these copies a disk.
  • Your account, your data. The control plane, the database, the bucket that holds every disk, the logs, the metrics and the traces all stay in your AWS account. There is no hosted part of Spinbox for any of it to be sent to.
  • Machines you do not patch. Every machine boots Spin OS, a read-only image with a verified root filesystem. An update replaces the machine with one built from the new release. See Update.
  • Pay for runners only while they work. Runners are large spot machines. The control plane starts one when a workspace needs it and removes it when nothing has run for a while. See Cost.

An installation is made of four repositories under github.com/spin-stack:

ProjectWhat it is
spinThe platform: control plane, runner, proxy, CLI, dashboard, and the programs that run inside a workspace.
spin-machineThe virtual machine: QEMU, the guest kernel, the base image, and the definition of the machine they make.
ami (Spin OS)The operating system every EC2 machine of an installation boots, with a release of spin already inside.
spin-terraform-awsThe OpenTofu module that creates an installation in an AWS account.

A release of spin names the release of spin-machine it runs. A Spin OS image is built for one release of spin. The OpenTofu module boots the published images of the release you choose.

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