# Spinbox

> Spinbox is experimental: APIs change and data may be lost. Self-hosted sandboxes in your own AWS account, a virtual machine per workspace, with snapshots, rollback and a diff of what changed.

Every page is also served as Markdown at the linked `.md` path, and all of them together at https://spin-stack.github.io/website/llms-full.txt.

## API

- [OpenAPI document](https://spin-stack.github.io/website/openapi.json): the control plane's API, spin.v1, of the commit this site documents; every procedure is a Connect unary call.

## Start here

- [What is Spinbox](https://spin-stack.github.io/website/overview.md): What Spinbox is, who it is for, what it lets you do, and the projects an installation is made of.
- [Status](https://spin-stack.github.io/website/reference/status.md): What Spinbox does today with what proves each, what is partly there, what is not built, and its limits, each row held to the code.
- [How it works](https://spin-stack.github.io/website/overview/how-it-works.md): The pieces of an installation (control plane, proxy, runners, database, bucket), how they connect, and how a workspace comes to run.
- [Quickstart](https://spin-stack.github.io/website/quickstart.md): Sign in to an installation, create a workspace, take a snapshot, change something, see the diff, and go back.
- [Try it on one machine](https://spin-stack.github.io/website/overview/one-machine.md): The development stack on a single Linux host with KVM - from git clone to a running workspace and a command in it. Not an installation.
- [Limitations](https://spin-stack.github.io/website/overview/limitations.md): Where Spinbox runs and the limits to know before you rely on it. What is built and what is not is on the status page.

## Concepts

- [Workspaces](https://spin-stack.github.io/website/concepts/workspaces.md): What a workspace is, its states, its resources and disk, what runs inside it, and how it is started, stopped, suspended and recovered.
- [Snapshots and rollback](https://spin-stack.github.io/website/concepts/snapshots.md): Disk and memory snapshots, restoring and resetting a workspace, diffing two snapshots, cloning, and sharing a snapshot with others.
- [Images](https://spin-stack.github.io/website/concepts/images.md): What an image is in Spinbox, the default image, how an administrator publishes and retires images, and how to build your own starting point from a snapshot.
- [Disks and storage](https://spin-stack.github.io/website/concepts/volumes.md): How a workspace's disk is stored: layers in the bucket, a cache on the runner, encryption, when work is uploaded, and what deleting removes.
- [Network and egress](https://spin-stack.github.io/website/concepts/network.md): How network policies control where a workspace connects, what is always blocked, how DNS works, and how to see what it reached.
- [Ports and sharing](https://spin-stack.github.io/website/concepts/ports.md): How to reach a service running in a workspace over HTTPS, who can reach it, and how to share it with other users or make it public.
- [Runners and hosts](https://spin-stack.github.io/website/concepts/runners.md): What a runner is, how it joins, how workspaces are placed on it, how runners scale from zero, and what happens when one is lost.

## Use Spinbox

- [The CLI](https://spin-stack.github.io/website/use/cli.md): Install the spin CLI, sign in, use profiles for several installations, and get JSON output for scripts.
- [Editors and SSH](https://spin-stack.github.io/website/use/editors.md): Connect to a workspace with spin ssh, plain ssh, scp and rsync, VS Code Remote-SSH, or the terminal in the dashboard.
- [Agents and automation](https://spin-stack.github.io/website/use/agents.md): Give an agent or a CI job its own API key, let it create workspaces it cannot escape, and use snapshots, diffs and clones to review and undo its work.
- [An agent without keys](https://spin-stack.github.io/website/use/agent-keys.md): Run a coding agent that needs a provider key inside a workspace, with the key never on its disk: a brokered policy, a team secret and a tag.
- [The dashboard](https://spin-stack.github.io/website/use/dashboard.md): What the dashboard shows, in screenshots spin's own dashboard suite takes of a real installation.

## Install on AWS

- [Install on AWS](https://spin-stack.github.io/website/aws/overview.md): What an installation on AWS is made of, what the OpenTofu module creates in your account, and the choices it makes for you.
- [Before you start](https://spin-stack.github.io/website/aws/prerequisites.md): The tools, AWS account, region, domain and spot quota you need before installing Spinbox on AWS.
- [Install](https://spin-stack.github.io/website/aws/setup.md): Install Spinbox in an AWS account step by step, from the state bucket to the first sign-in and the first workspace.
- [Network](https://spin-stack.github.io/website/aws/network.md): What the internet can reach in an installation, which machine talks to which on what port, and how to close the installation to your own networks.
- [Cost](https://spin-stack.github.io/website/aws/cost.md): What an installation costs on AWS: the small part that runs all the time, the runners that run only while workspaces do, and the settings that change it.
- [Update](https://spin-stack.github.io/website/aws/update.md): Move an installation to a new release, and what happens to its machines and workspaces while it rolls out.
- [Remove](https://spin-stack.github.io/website/aws/remove.md): Delete an installation on purpose: what refuses to be destroyed, why, and the steps to remove it anyway.
- [Troubleshooting](https://spin-stack.github.io/website/aws/troubleshooting.md): Where to look when an installation does not come up, a workspace waits for a host, a start fails, or a workspace cannot reach something.

## Administer

- [Installation settings](https://spin-stack.github.io/website/admin/configuration.md): How an installation is configured: the file that seeds it, the dashboard that edits it, and how a changed file becomes a proposal.
- [Users and teams](https://spin-stack.github.io/website/admin/users.md): How people sign in, who may register, administrators, teams and their roles, API keys, and the audit log.
- [Operating hosts](https://spin-stack.github.io/website/admin/hosts.md): Drain, activate and revoke runners, see what runs where, replace a runner's machine, and add a runner outside the autoscaling group.
- [Observability](https://spin-stack.github.io/website/admin/observability.md): The logs, traces and metrics an installation keeps about itself and its workspaces, where they are kept, how long, and how administrators read them.
- [Backups and recovery](https://spin-stack.github.io/website/admin/recovery.md): What an installation's durable state is, how each part is backed up, and what can be recovered after losing a runner, a machine, or the database.

## Security

- [Security model](https://spin-stack.github.io/website/security.md): What Spinbox protects, from whom, and how: isolation, network, data, identity and supply chain, and where to read about each.
- [Isolation](https://spin-stack.github.io/website/security/isolation.md): What keeps a workspace from the runner, other workspaces and the cloud: the virtual machine, its confined QEMU, and how disk bytes are parsed.
- [Data and encryption](https://spin-stack.github.io/website/security/data.md): How disks, memory snapshots and the installation's secrets are encrypted, where each key lives, and what each kind of delete destroys.
- [Identity and access](https://spin-stack.github.io/website/security/identity.md): How users, API keys, runners and machines prove who they are, how every request is authorized, and what limits each machine's cloud role.
- [Supply chain](https://spin-stack.github.io/website/security/supply-chain.md): How a release is built, signed and verified, how Spin OS makes every machine run exactly what the release signed, and what each image is made of.
- [Rules and their gates](https://spin-stack.github.io/website/reference/security/rules.md): The rules every entry point of Spinbox must keep, and the test or lint that fails the build when one is broken.
- [Known gaps](https://spin-stack.github.io/website/reference/security/known-gaps.md): The parts of Spinbox's security model that are not enforced yet, each a design change rather than a patch.
- [Reporting a vulnerability](https://spin-stack.github.io/website/security/reporting.md): How to report a security problem in Spinbox privately, and what to include.

## Reference: CLI

- [CLI](https://spin-stack.github.io/website/reference/cli.md): Every command of the spin CLI, as its own --help says it: workspaces, snapshots, ports, keys, teams and administration.
- [spin admin](https://spin-stack.github.io/website/reference/cli/admin.md): spin admin: Administrative commands.
- [spin api-key](https://spin-stack.github.io/website/reference/cli/api-key.md): spin api-key: Manage API keys.
- [spin code](https://spin-stack.github.io/website/reference/cli/code.md): spin code: Open a workspace in VS Code.
- [spin cp](https://spin-stack.github.io/website/reference/cli/cp.md): spin cp: Copy files to or from a workspace.
- [spin exec](https://spin-stack.github.io/website/reference/cli/exec.md): spin exec: Run a command in a workspace.
- [spin login](https://spin-stack.github.io/website/reference/cli/login.md): spin login: Authenticate with the platform.
- [spin logout](https://spin-stack.github.io/website/reference/cli/logout.md): spin logout: End the profile's session and forget its login.
- [spin open](https://spin-stack.github.io/website/reference/cli/open.md): spin open: Open a repository, branch, commit or pull request from its URL.
- [spin port](https://spin-stack.github.io/website/reference/cli/port.md): spin port: Manage exposed ports for workspaces.
- [spin project](https://spin-stack.github.io/website/reference/cli/project.md): spin project: Manage a team's projects: a repository and the workspace that opens it.
- [spin settings](https://spin-stack.github.io/website/reference/cli/settings.md): spin settings: Manage user settings.
- [spin share](https://spin-stack.github.io/website/reference/cli/share.md): spin share: Manage snapshot sharing.
- [spin sign](https://spin-stack.github.io/website/reference/cli/sign.md): spin sign: Sign what only you can: your keyring and your teams' rosters.
- [spin smoke](https://spin-stack.github.io/website/reference/cli/smoke.md): spin smoke: Check an installation does what its API promises, with a workspace of its own.
- [spin snapshot](https://spin-stack.github.io/website/reference/cli/snapshot.md): spin snapshot: Take, list and delete a workspace's snapshots.
- [spin ssh](https://spin-stack.github.io/website/reference/cli/ssh.md): spin ssh: SSH into a workspace.
- [spin ssh-config](https://spin-stack.github.io/website/reference/cli/ssh-config.md): spin ssh-config: Make every workspace reachable with plain ssh, as the host spin.<workspace>.
- [spin ssh-key](https://spin-stack.github.io/website/reference/cli/ssh-key.md): spin ssh-key: Manage SSH keys.
- [spin team](https://spin-stack.github.io/website/reference/cli/team.md): spin team: Manage teams.
- [spin trust](https://spin-stack.github.io/website/reference/cli/trust.md): spin trust: What this machine trusts of an installation.
- [spin version](https://spin-stack.github.io/website/reference/cli/version.md): spin version: Print version information.
- [spin whoami](https://spin-stack.github.io/website/reference/cli/whoami.md): spin whoami: Show current user info.
- [spin workspace](https://spin-stack.github.io/website/reference/cli/workspace.md): spin workspace: Manage workspaces.

## Reference: Terraform

- [The installation module](https://spin-stack.github.io/website/reference/terraform/root.md): spin-terraform-aws, the module an installation uses: every variable it takes and every output it gives.
- [modules/controlplane](https://spin-stack.github.io/website/reference/terraform/controlplane.md): spin-terraform-aws, the network, bucket, database, control plane and proxy, used on its own.
- [modules/runners](https://spin-stack.github.io/website/reference/terraform/runners.md): spin-terraform-aws, the runners' autoscaling group, used on its own.
- [bootstrap](https://spin-stack.github.io/website/reference/terraform/bootstrap.md): spin-terraform-aws, the once-per-account state bucket and key, and CI's roles.
- [Spin OS images](https://spin-stack.github.io/website/reference/terraform/images.md): The Spin OS images the module boots for the release this site documents, by region, from images.json.

## Reference: Configuration

- [Installation config file](https://spin-stack.github.io/website/reference/configuration/file.md): The installation's config file: settings, registration, workspace presets and network policies, with the comment on each.

## Reference: API

- [API](https://spin-stack.github.io/website/reference/api.md): The control plane's API, spin.v1: every service and procedure, generated from its OpenAPI document.
- [AuthService](https://spin-stack.github.io/website/reference/api/authservice.md): spin.v1.AuthService: each procedure, its request and its response.
- [AdminService](https://spin-stack.github.io/website/reference/api/adminservice.md): spin.v1.AdminService: each procedure, its request and its response.
- [HostService](https://spin-stack.github.io/website/reference/api/hostservice.md): spin.v1.HostService: each procedure, its request and its response.
- [LogService](https://spin-stack.github.io/website/reference/api/logservice.md): spin.v1.LogService: each procedure, its request and its response.
- [RunnerTokenService](https://spin-stack.github.io/website/reference/api/runnertokenservice.md): spin.v1.RunnerTokenService: each procedure, its request and its response.
- [SettingsService](https://spin-stack.github.io/website/reference/api/settingsservice.md): spin.v1.SettingsService: each procedure, its request and its response.
- [SetupService](https://spin-stack.github.io/website/reference/api/setupservice.md): spin.v1.SetupService: each procedure, its request and its response.
- [WorkspaceService](https://spin-stack.github.io/website/reference/api/workspaceservice.md): spin.v1.WorkspaceService: each procedure, its request and its response.
- [ShareService](https://spin-stack.github.io/website/reference/api/shareservice.md): spin.v1.ShareService: each procedure, its request and its response.
- [SignatureService](https://spin-stack.github.io/website/reference/api/signatureservice.md): spin.v1.SignatureService: each procedure, its request and its response.
- [SSHKeyService](https://spin-stack.github.io/website/reference/api/sshkeyservice.md): spin.v1.SSHKeyService: each procedure, its request and its response.
- [TeamService](https://spin-stack.github.io/website/reference/api/teamservice.md): spin.v1.TeamService: each procedure, its request and its response.
- [Types](https://spin-stack.github.io/website/reference/api/types.md): Every message and enum the spin.v1 procedures name, with their fields and values.