# Installation settings

**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 an installation is configured: the file that seeds it, the dashboard that edits it, and how a changed file becomes a proposal.

An installation's settings live in its database, and an administrator edits all of them in the
dashboard. A **config file** is where they start.

## The config file seeds

On AWS, the file is `installation_config` in Terraform:

```hcl
module "spin" {
  # ...
  installation_config = file("installation.yaml")
}
```

When the control plane starts, [it creates each item of the file that the installation does not
have yet](https://docs.spinbox.dev/reference/status.md#administration): a setting, a preset, a network policy. From then on, the dashboard is where they change.

When the file later says something different about an item, the control plane does **not** write
over what an administrator decided. It records the difference as a **proposal**, and the dashboard
shows it with **Apply** and **Dismiss**. An item the file stops declaring becomes a proposal to
delete it; nothing is removed without an administrator deciding. A dismissed proposal stays
hidden until the file changes again.

This is how a new release's defaults reach an installation that already runs: as proposals, not
as surprises.

Check a file before you apply it:

```bash
controlplane config check installation.yaml
```

The whole file, with the comment on every field, is in the
[config file reference](https://docs.spinbox.dev/reference/configuration/file.md).

## What it holds

The installation's settings, who may register, the sizes a workspace may be created with, and the
network policies it may run under. Each block, with every field and its default, is in the
[config file reference](https://docs.spinbox.dev/reference/configuration/file.md), written from the example file the
control plane's own test reads.

On AWS the module adds what it knows itself: the domain, which machines join as runners, and the
autoscaling settings.

## Changing a setting

Every setting has one definition, and the file, the dashboard and the terminal all read it.
[`spin admin settings get` lists every setting as it is in force, with where it is changed, and
`spin admin settings set` changes one](https://docs.spinbox.dev/reference/status.md#administration):

```bash
spin admin settings get
spin admin settings set session_duration_hours 72
```

Most settings can be seeded by the file too. A few are the file's alone, such as the base domain,
and a few have a page of their own that checks them before they are written, such as the object
store and the mail server. Among the ones an administrator changes:

- **Session length**: seven days by default, at most fourteen.
- **Sharing**: whether workspaces may be shared (on by default), and whether ports and snapshots
  may be made public (off by default).
- **Rate limits** on sign-in and on the API.
- **Telemetry**: which traces and metrics are kept. See [Observability](https://docs.spinbox.dev/admin/observability.md).
- **A root shell on a host**: whether another administrator approves each one, and how long it
  may stay open. See [Operations](https://docs.spinbox.dev/admin/operations.md).

Sign-in providers, GitHub and OIDC, are not settings: they are in **Admin → Security**. See
[Users and teams](https://docs.spinbox.dev/admin/users.md).
