# What is 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).

> What Spinbox is, who it is for, what it lets you do, and the projects an installation is made of.

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.

## Who it is for

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

## What you can do

| You want to | Spinbox gives you |
|---|---|
| Start from a known state | A workspace cloned from an image or from any snapshot, without copying a disk |
| Keep a point to come back to | [A snapshot of the disk](https://docs.spinbox.dev/reference/status.md#snapshots), or [of the disk and memory together](https://docs.spinbox.dev/reference/status.md#snapshots) |
| Undo | [Restore the disk to a snapshot](https://docs.spinbox.dev/reference/status.md#snapshots), or resume a memory snapshot with its processes |
| See what changed | [A file-by-file diff between two snapshots](https://docs.spinbox.dev/reference/status.md#snapshots), computed in a separate machine |
| Control what code reaches | [Network policies](https://docs.spinbox.dev/reference/status.md#network): a workspace reaches nothing until a policy lets it |
| Reach a service inside | `https://<port>-<workspace>.ws.<your domain>`, private to you until you share it |
| Hand work to an agent | [API keys with scopes](https://docs.spinbox.dev/reference/status.md#access), and a CLI that prints JSON |

Each is a built feature, with what proves it on the status page:
[workspaces](https://docs.spinbox.dev/reference/status.md#workspaces), [snapshots](https://docs.spinbox.dev/reference/status.md#snapshots) and
[network](https://docs.spinbox.dev/reference/status.md#network). See [Workspaces](https://docs.spinbox.dev/concepts/workspaces.md) and
[Snapshots and rollback](https://docs.spinbox.dev/concepts/snapshots.md) for the details.

## Questions people ask first

### Is there a hosted version?

No. Spinbox runs in your AWS account, installed by one OpenTofu module. See
[Install on AWS](https://docs.spinbox.dev/aws/overview.md).

### What does it cost?

A small part runs all the time, and runners run only while workspaces do. See [Cost](https://docs.spinbox.dev/aws/cost.md).

### Can I try it without AWS?

Yes, on one Linux machine with KVM: [Try it on one machine](https://docs.spinbox.dev/overview/one-machine.md).

### Does it need Kubernetes?

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

### What does it not do yet?

[Status](https://docs.spinbox.dev/reference/status.md) lists every feature with what proves it, says where a test can't
reach, and lists what is not built. [Limitations](https://docs.spinbox.dev/overview/limitations.md) lists what Spinbox does not do by design.

### How do I report a security problem?

Privately, through a security advisory: see [Reporting a vulnerability](https://docs.spinbox.dev/security/reporting.md).

## Why it is built this way

- **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](https://docs.spinbox.dev/security/isolation.md).
- **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](https://docs.spinbox.dev/aws/update.md).
- **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](https://docs.spinbox.dev/aws/cost.md).

## The projects

An installation is made of four repositories under
[github.com/spin-stack](https://github.com/spin-stack):

| Project | What it is |
|---|---|
| **spin** | The platform: control plane, runner, proxy, CLI, dashboard, and the programs that run inside a workspace. |
| **spin-machine** | The 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-aws** | The 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.

## Next

- [How it works](https://docs.spinbox.dev/overview/how-it-works.md): the pieces and how they talk.
- [Quickstart](https://docs.spinbox.dev/quickstart.md): use an installation that already exists.
- [Install on AWS](https://docs.spinbox.dev/aws/overview.md): make your own.
