# Profiles

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

> How to set the module for one person, one person with agents, a small team, a team of twenty and a hundred people, and what each choice trades.

The module's defaults are a small installation: at most one runner
([`max_runners`](https://docs.spinbox.dev/reference/terraform/root.md#max_runners)), of 32 to 48 vCPUs
([`runner_vcpus`](https://docs.spinbox.dev/reference/terraform/root.md#runner_vcpus)), on spot, given back once nothing has
run for [`runner_idle_minutes`](https://docs.spinbox.dev/reference/terraform/root.md#runner_idle_minutes). Each profile below
says who it is for, what to change from those defaults and why, what that trades, and what has not
been tried. [Cost](https://docs.spinbox.dev/aws/cost.md) says what each part is billed at; this page does not repeat it.

The settings are arguments of `module "spin"`, in your copy of `examples/complete` (its `main.tf`,
which already sets `runner_idle_minutes`, `quiet_hours`, `time_zone` and `max_runners`). Its
`terraform.tfvars` takes only the example's own variables, such as `spin_version` and `domain`.
Every argument, with its default, is in the [module reference](https://docs.spinbox.dev/reference/terraform/root.md).

Two things no profile changes yet. How many workspaces fit on one runner has not been measured, so
every `max_runners` below is a starting point to correct against what you see. And the control
plane and the proxy run all the time: there is no standby that stops them while nobody works, nor a
smaller installation for one person than the one the module makes.

## What each might cost

A model, not a bill: us-east-1, AWS's prices of 2026-11-19, spot runners at their 30-day median
price ([Spot](https://docs.spinbox.dev/aws/cost.md#spot)), the part that runs all the time at the one measurement so far
([With nobody working](https://docs.spinbox.dev/aws/cost.md#with-nobody-working)), and, the largest unknown, eight
workspaces on a runner. Each line is in dollars a month.

| Profile | What the model assumes | About | Each person |
|---|---|---|---|
| One person | One or two workspaces through the working day | $165 | $165 |
| One person with agents | The person, and four agents' workspaces through the working day | $230 | $230 |
| Agents around the clock | The person, and three agents' workspaces never stopping | $560 | $560 |
| Small team | Five people | $210 | $42 |
| Team | 22 people in two time zones, a few agents, light CI | $950 | $43 |
| Large | 100 people in three time zones, agents, CI and prebuilds, a larger control plane | $4,100 | $41 |

The share of a person moves most with density: at four workspaces a runner rather than eight, the
team of 22 is about $1,560 a month, and at sixteen about $650. With every runner on demand, each
line is more than double. What a workspace writes to the bucket, and what it sends out
of the region, are guesses too; they matter most for agents.

## One person

**For** a developer on their own, with a workspace or two open while they work.

The defaults fit. What is worth setting:

```hcl
module "spin" {
  # ...
  quiet_hours        = "20:00-07:00"
  time_zone          = "Europe/Madrid"
  monthly_budget_usd = 200
  budget_emails      = ["you@example.com"]
}
```

- `quiet_hours` and `time_zone`: at night the runner goes as soon as nothing runs, instead of
  after `runner_idle_minutes`.
- `monthly_budget_usd` and `budget_emails`: a mail when the month passes 80% or 100% of it, or is
  forecast to. It stops nothing.

**Trades.** The first workspace after the runner has gone waits while a new one starts
(*Waiting for a host*). A lower `runner_idle_minutes` saves runner hours and makes that wait more
frequent.

**A smaller runner.** Most of one person's bill is a runner of 32 vCPUs or more kept up for a few
cores of work, and the parts that run all the time. A runner of 8 vCPUs would cut the first:

```hcl
  runner_vcpus = { min = 8, max = 8 }
```

The module accepts it, and the group then asks for the 2xlarge sizes of the default families with
local NVMe. In the model above, it takes one person from about $165 to about $100 a month. **No installation has run runners that small.** A preset as large as the runner leaves
nothing for the host itself, so keep presets well under it
([Installation settings](https://docs.spinbox.dev/admin/configuration.md)); and with `max_runners` still one, a workspace
that does not fit waits for room.

## One person with agents

**For** a person who runs agents in workspaces of their own beside the one they work in, including
workspaces that run for days.

```hcl
module "spin" {
  # ...
  max_runners        = 2
  runner_rollout     = "rolling"
  monthly_budget_usd = 600
  budget_emails      = ["you@example.com"]
}
```

- `max_runners = 2`: if the agents' workspaces do not fit on one runner, the next one can go to
  another runner instead of waiting for room on the first. The control plane adds a runner only when a workspace
  has waited ten minutes ([Scaling from zero](https://docs.spinbox.dev/concepts/runners.md#scaling-from-zero)).
- `runner_rollout = "rolling"`: with the default, `idle`, a new release reaches the runners only
  once the fleet empties, which a fleet with a workspace that never stops does not. Rolling
  replaces them at an update, each workspace suspended and resumed on the new host
  ([Update](https://docs.spinbox.dev/aws/update.md)).
- A budget: a workspace that runs for days keeps a runner up for days, and the bill shows it.

Not Terraform, and the setting a workspace that runs for days meets first: the installation
[suspends a workspace that has run as long as it allows](https://docs.spinbox.dev/reference/status.md#workspaces),
used or not, 12 hours by default. An administrator sets it, from no cap to a week:

```bash
spin admin settings get workspace_max_running_minutes
spin admin settings set workspace_max_running_minutes 0
```

Zero caps none. The owner of one workspace can instead keep it awake for a while
([Workspaces](https://docs.spinbox.dev/concepts/workspaces.md)).

**Trades.** Without the cap, a forgotten workspace keeps its runner up until somebody stops it. On
spot, AWS can take a runner back at any time: [its workspaces are suspended to the bucket and
resumed on another](https://docs.spinbox.dev/reference/status.md#administration),
which an agent in the middle of a task sees as a pause. `runner_spot = false` avoids that at the
on-demand price ([Spot](https://docs.spinbox.dev/aws/cost.md#spot)). A workspace that runs for a long time without stopping
also meets the [disk chain's limit](https://docs.spinbox.dev/overview/limitations.md#workspaces).

**Not tried.** The agent features are built and tested, and the least used day to day. Agents
running for days on one installation, and how often spot interrupts a runner over a week, have not
been measured.

## Small team

**For** about five people in one time zone.

```hcl
module "spin" {
  # ...
  max_runners        = 2
  quiet_hours        = "20:00-07:00"
  time_zone          = "America/New_York"
  monthly_budget_usd = 400
  budget_emails      = ["ops@example.com"]
}
```

- `max_runners = 2`: at the density assumed above, five people fit on one runner; another covers
  being wrong about it, and busy days.
- `quiet_hours` in the team's time zone: the runner goes as soon as the last person stops.

**Trades.** The next runner starts only after a workspace has waited ten minutes, so on a busy
morning someone waits. Once every runner is up, a workspace that does not fit waits for room.

**Not tried.** How many workspaces fit on a runner. [The bill](https://docs.spinbox.dev/admin/operations.md#the-bill) shows
what each workspace held, and the runners' capacity nobody held, which is the measure to correct
`max_runners` by.

## Team

**For** twenty to twenty-five people, in one or two time zones.

```hcl
module "spin" {
  # ...
  max_runners        = 6
  quiet_hours        = "22:00-06:00"
  time_zone          = "Europe/Berlin"
  monthly_budget_usd = 1500
  budget_emails      = ["ops@example.com"]
}
```

- `max_runners = 6`: what the model needs at its busiest hour at eight workspaces a runner. At four
  it would need eleven, at sixteen three. `request_quota` (on by default) asks AWS for the spot
  vCPUs that many runners of `runner_vcpus`' maximum take ([Before you start](https://docs.spinbox.dev/aws/prerequisites.md)).
- `quiet_hours` only over the hours neither time zone works, or none: inside the window a gap
  between two people empties the fleet, and the next one waits for a runner.
- Keep `runner_instance_types` broad: each type and zone it matches is one more spot pool to start
  from ([Spot](https://docs.spinbox.dev/aws/cost.md#spot)).

**Trades.** Runners are given back one at a time, once a runner has held nothing only it holds
for `runner_idle_minutes`; a lower value gives runners back sooner and starts them more often.

**Not tried.** Density, as above, and twenty people on one installation.

## Large

**For** about a hundred people across time zones, with agents, CI jobs in workspaces, and
[prebuilds](https://docs.spinbox.dev/concepts/projects.md#prebuilds).

```hcl
module "spin" {
  # ...
  max_runners            = 20
  runner_rollout         = "rolling"
  instance_type          = "m8i.xlarge"
  controlplane_volume_gb = 200
  monthly_budget_usd     = 6000
  budget_emails          = ["ops@example.com"]
}
```

- `max_runners = 20`: the model's busiest hour at eight workspaces a runner; between ten and
  forty over the densities it was run at.
- `runner_rollout = "rolling"`: a fleet working across time zones may never empty.
- `instance_type` and `controlplane_volume_gb`: the control plane also runs the database and the
  stores of logs, traces and metrics, and nothing in the module sizes it by how many people use
  it. These two values are a guess, not a measurement: watch its machine
  ([Observability](https://docs.spinbox.dev/admin/observability.md)) and size it from that. A change replaces the machine,
  as an [update](https://docs.spinbox.dev/aws/update.md) does.
- Without quiet hours: someone is always working.

**Trades.** Spot capacity for many runners at once is less sure than for one: AWS's placement
score for the default types fell at 20 runners in us-east-1 and held in us-west-2 on the day it was
read ([Spot](https://docs.spinbox.dev/aws/cost.md#spot)). A host class can fall back to on demand when spot is refused
(Admin → Runners). The control plane and the proxy are still one machine each
([Limitations](https://docs.spinbox.dev/overview/limitations.md#where-it-runs)). Prebuilds keep their disks in the bucket
until retired, which an administrator can make automatic for unused ones in the installation's
settings.

**Not tried.** A hundred people, the control plane at that load, the proxy
([`proxy_instance_type`](https://docs.spinbox.dev/reference/terraform/controlplane.md#proxy_instance_type)) at that
traffic, and twenty runners on spot at once.

## For every profile

- After the installation has run for a while, switch on its cost allocation tags in bootstrap, or
  the Costs page stays empty ([Reading the bill](https://docs.spinbox.dev/aws/cost.md#reading-the-bill)).
- [`runner_spot`](https://docs.spinbox.dev/reference/terraform/root.md#runner_spot),
  [`runner_instance_types`](https://docs.spinbox.dev/reference/terraform/root.md#runner_instance_types) and
  [`runner_vcpus`](https://docs.spinbox.dev/reference/terraform/root.md#runner_vcpus) change what a runner is; keep the types
  to one CPU generation, so that a suspended workspace can resume on any of them rather than boot
  cold.
- How long a workspace may sit unused before it is suspended is an installation setting, like the
  running cap above: [Installation settings](https://docs.spinbox.dev/admin/configuration.md).
