# Spinbox

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> Workspaces in your own AWS account, each a virtual machine built from parts Linux and QEMU already have, with snapshots, rollback and a diff of what changed.

## Break it. See it. Undo it.

1. **Take a snapshot, memory and all.** A machine of its own, and a snapshot of its disk with the memory of every running process. ([status](https://docs.spinbox.dev/reference/status.md#snapshots))

```bash
spin workspace create --name demo --wait
spin snapshot create demo --description clean --with-memory --wait
```

2. **Let anyone break anything.** A person or an agent is root in a KVM machine with its own kernel, not in a container that shares the host's. ([status](https://docs.spinbox.dev/reference/status.md#workspaces))

```bash
spin exec demo -- sh -c 'echo hello > /etc/greeting; rm /etc/issue; echo "# edited" >> /etc/hosts'
spin snapshot create demo --description after --wait
```

3. **See what changed.** The files added, modified or removed between two snapshots, read by a separate machine. ([status](https://docs.spinbox.dev/reference/status.md#snapshots))

```bash
spin snapshot diff demo <after-id> --from <clean-id> --under /etc
```

```text
A  /etc/greeting
M  /etc/hosts
D  /etc/issue
```

4. **Go back as if it never happened.** The disk as it was, and the processes running where they were. ([status](https://docs.spinbox.dev/reference/status.md#snapshots))

```bash
spin workspace restore demo <clean-id> --with-memory
spin workspace delete demo
```

## Three things it does

- **[Isolate: a whole machine, not a container](https://docs.spinbox.dev/reference/status.md#workspaces).** Every workspace is a KVM virtual machine with its own kernel, root and a persistent disk. A person or an agent can install anything and break anything inside it. Around it, the QEMU process runs as a user of its own, opens nothing by name and has no network, and each machine sits in a network namespace of its own. What that boundary covers, and what it doesn't yet, is in the [security model](https://docs.spinbox.dev/security.md).
- **[Inspect: snapshot, diff, roll back](https://docs.spinbox.dev/reference/status.md#snapshots).** A snapshot before, with the memory of the running processes. The files added, modified or removed between two snapshots, read by a separate machine. Restore, and the processes are running where they were.
- **[Control: closed until you open it](https://docs.spinbox.dev/reference/status.md#network).** Egress is closed by default, and policies name what a workspace may reach. A team's secret stays on the host's proxy and never enters the workspace. All of it in your AWS account, where the logs stay too.

*Diagram: Where the boundary is: people and agents reach the proxy; the control plane, the runners, the buckets and the keys are the module's, in your account and your region.* Its labels: AWS · Users browser, spin CLI, SSH · Let's Encrypt · Region · spin-stack/ami task release · images.json release → region → AMI · operator tofu apply, or GitHub Actions · VPC - no NAT: every machine has its own way out · Internet gateway · edge subnets the proxy's alone · public subnets, one per zone · S3 gateway endpoint · S3 - only through the endpoint volumes (Object Lock), the database's sealed archive, logs, certificates; a document per role, by the apply · Parameter Store - written by the apply the key, the CA, the first password: the control plane's alone · Route 53 <domain>, which its registrar points at, and spin.internal, whose records the machines write · IAM a role per machine, one permissions boundary · Spin OS AMI the release, read-only root · CloudWatch Logs every boot, the VPC's flows · Session Manager the only shell · OpenTofu state S3, encrypted with KMS · Elastic IP app., tunnel.app., *.ws. · proxy, a group of one · control plane a group of one, replaced beside itself · runners 0 to max_runners spot hosts, sized by the control plane · Caddy TLS and the relay · spin control plane · PostgreSQL · VictoriaMetrics Quickwit, Alloy · Grafana · spin runner nftables per workspace · workspace VMs QEMU/KVM · 8080, dialled out · 443, and 80 for the challenge · 8080 · the relay: the runner dials 443 · nothing listens on a runner · volumes: an hour's minted credential · pull request · 443 · 80 · the network, the machines' groups, their documents and secrets. ([source](https://github.com/spin-stack/spin-terraform-aws/blob/358445c95280923876ef3e95658fe45e367462a1/docs/diagrams/installation))

## And

- **Ready for agents.** [Claude Code and Codex on every workspace's PATH](https://docs.spinbox.dev/reference/status.md#workspaces), API keys with scopes, JSON output.
- **Secrets the workspace never holds.** [A brokered rule](https://docs.spinbox.dev/reference/status.md#network) adds the team's secret on the way out, one for the person and one for the agent.
- **Moves while it runs.** [A running workspace goes to another host](https://docs.spinbox.dev/reference/status.md#workspaces) with its processes as they are.
- **Asleep when idle, awake as it was.** [A workspace nobody uses is suspended](https://docs.spinbox.dev/reference/status.md#workspaces), after asking first, and a start resumes it.
- **Reset in one command.** [A disk goes back to what it was created from](https://docs.spinbox.dev/reference/status.md#workspaces), its snapshots kept.
- **In your AWS account.** [One OpenTofu module installs it](https://docs.spinbox.dev/aws/overview.md). There is no hosted version, so your code and your data stay in your account.

## What's built, and what isn't

**96 features built**, each with a test or a command that proves it, 83 of them with an end-to-end test, 2 not built yet and 17 limits, on the [status page](https://docs.spinbox.dev/reference/status.md). An installation runs release `v20261027.01`; the reference is generated from spin `v20261114.01` (`51f7e0dea`).

## Straight answers

- **AWS only.** One OpenTofu module installs Spinbox in your account. There is no hosted version.
- **x86-64 only.** Runners are x86-64 machines with nested virtualization.
- **Linux guests only.** A workspace boots the kernel Spinbox provides.
- **No GPUs.** A preset names the class of runner its workspaces run on, and no class hands a workspace a GPU.
- **One region, one control plane.** An installation lives in one AWS region.

Each answer is a limit row of the [status page](https://docs.spinbox.dev/reference/status.md).
The rest are on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

**Workspaces you own, from the first snapshot.** What it is for, what it costs to run, how to try it on one machine, and how to install it.

- [Evaluate Spinbox](https://docs.spinbox.dev/overview/evaluate.md)
- [Install on AWS](https://docs.spinbox.dev/aws/overview.md)
- [Quickstart](https://docs.spinbox.dev/quickstart.md)
- [For agents](https://docs.spinbox.dev/use/agents.md)
