Install on AWS

An installation of Spinbox lives in one AWS account and one region. It is created by one OpenTofu module, spin-terraform-aws:

module "spin" {
  source       = "github.com/spin-stack/spin-terraform-aws?ref=<tag>"
  spin_version = "v20261019.02"
  domain       = "spin.example.com"
}

What the module creates in your account, and who connects to whom. Its source.

What it creates

• A VPC of its own, with public subnets and no NAT gateway. The bucket is reached through the free S3 gateway endpoint.
• The control plane, on one machine (instance_type), in an autoscaling group of one. It also runs the installation’s PostgreSQL 18 and its log and metric stores.
• The proxy, on one machine (proxy_instance_type) with an elastic IP, in an autoscaling group of one.
• The runners, an autoscaling group of large spot machines with local NVMe (instance_types), which the control plane sizes from zero.
• S3 buckets, each with one owner: the volumes, with versioning and Object Lock; the database’s archive, under Object Lock too; logs, traces and metric backups; the proxy’s certificates; and what each machine starts from.
• Two Route 53 zones: your domain’s public zone, and a private zone (spin.internal) the machines find each other by.
• The installation’s secrets, in SSM Parameter Store: its CA, its encryption key and the first administrator’s password.
• IAM roles for each machine, all under one permissions boundary.
• A VPC flow log, kept in CloudWatch for 30 days.

Every machine boots Spin OS, the image published for the release, in the regions Spin OS images lists.

The choices it makes

These are made for you, and each one has a reason:

Choice	Why
Every machine is replaced to update, never patched	Its root filesystem is read-only and verified; a machine runs exactly what the release signed.
The proxy is the only machine the internet reaches	The control plane, the runners and the database take no connection from outside the VPC.
No SSH on any machine	A shell is AWS Session Manager, decided by IAM and logged by AWS.
No NAT gateway	It would cost more than the machines that run all the time.
Runners are spot and start from zero	They are the largest cost, and they only cost while a workspace runs.
Runners join by their IAM role	There is no join token to create, store, rotate or leak.
No role can grant itself more	A permissions boundary on every role denies IAM writes, parameter writes, and lifting the bucket’s lock.
Telemetry stays in the installation	Logs, traces and metrics are kept on the control plane’s machine, over the logs bucket.

Before you begin

Read Before you start: you need a domain of the installation’s own, room in your account’s spot quota, and a region the release has images in.

Pages in this section

• Before you start: tools, domain, quotas and the image.
• Install: the commands, in order.
• Network: what reaches what, and how to close the installation to your own networks.
• Cost: what runs all the time, and what runs only while workspaces do.
• Update: moving to a new release.
• Remove: deleting an installation on purpose.
• Troubleshooting: where to look when something does not come up.