# Sandboxes

A short-lived copy of the whole application, with its own built-ins, credentials, network and lifetime.

A sandbox runs everything `parity.yaml` describes: every service, every built-in and every job, from the same images staging and production run. It exists for one task, one branch or one agent, and is deleted with all its data when its time is up.

## What each sandbox gets [#what-each-sandbox-gets]

| | |
| --- | --- |
| Namespace | Its own Kubernetes namespace, default-deny network policy and resource quota. |
| Built-ins | Its own Postgres, Redis, S3 buckets, inbox, OIDC issuer and certificate authority, with generated credentials. |
| Secrets | Generated per sandbox. A sandbox never reads staging or production secrets. |
| Hostnames | `<host>--<sandbox>--<account>.env.parity.ninja`, with TLS. |
| Egress | Only the [`externals`](/manifest/externals) hosts its services list that the promoted manifest also allows. |
| Token | A sandbox token, printed once at creation, that reaches this sandbox only. |
| Lifetime | 2 hours by default, extendable up to `sandbox.max_ttl` (24 hours by default). |

Inside a sandbox, services and built-ins reach each other by name: `db:5432`, `cache:6379`, `http://web:8080`.

## Lifecycle [#lifecycle]

```text title="States"
starting ⇄ ready → expiring
   ↘ failed
```

1. **Create.** `parity up` uploads the source, builds what changed, and creates the namespace and built-ins.
2. **Set up.** Jobs run by phase: `deploy`, then `seed`, then `start`. Within a phase they run in parallel unless `depends_on` orders them. A failed job fails the sandbox and its log tail is in the response.
3. **Ready.** Services start once setup is done and pass their health checks.
4. **Update.** `parity up` again rolls the sandbox onto new code or a changed manifest. Data and generated secrets stay; `deploy` jobs run again.
5. **Delete.** `parity down`, or the end of its lifetime, runs `destroy` jobs and deletes everything.

## Fast starts [#fast-starts]

An image built for the same files and build args is reused across all of a project's sandboxes, so a second sandbox on the same commit starts without building. With a [`develop`](/manifest/services#develop) block, an edit copies files into the running service instead of rebuilding: about 1 to 2 seconds for a synced change.

## Sizes and limits [#sizes-and-limits]

| Limit | Default |
| --- | --- |
| Sandbox ID | Lowercase letters, digits and single `-`, at most 26 characters |
| Lifetime | `ttl: 2h`, `max_ttl: 24h` (set in [`sandbox`](/manifest/advanced#sandbox)) |
| Replicas | 1 per service; `parity scale web 3` for one sandbox, at most 10 |
| Resources per service | 100m CPU and 256Mi requested, 2 CPU and 2Gi limit, unless `resources` says otherwise |
| Proof bundles | 20 per sandbox |

A manifest can make its sandboxes stricter than these, never looser.