# Boxes

> A box is a dedicated Linux machine in the size you pick, from Nano to Extra Large. Create and manage boxes from the CLI or the dashboard; connect to them with the CLI.

URL: https://prized.dev/docs/boxes

## Create [#create]

```bash
prized box new                                   # a fruit name, the size your balance runs comfortably
prized box new mango --size Small --ttl 4h --wait
```

Create from the CLI (flags under [CLI: box new](https://prized.dev/docs/cli#box-new)) or the dashboard's [New box](https://prized.dev/docs/dashboard#new-box) page. A Small box created with no name, snapshot, or environment is usually running the moment the create returns: one is kept ready for the next request. Every other box, and a Small box requested while the next ready one is still starting, boots in about a minute; `--wait` blocks until it is running. Sizes mix freely, each at its own rate ([Billing](https://prized.dev/docs/billing)); a size the balance could not run for four hours cannot be picked unless [overage](https://prized.dev/docs/billing#overage) is on.

`prized box ls` lists your boxes; `prized box info mango` shows one in full. What each size is made of is on [Machines](https://prized.dev/docs/machines).

## States [#states]

| State        | Meaning                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| running      | Up and reachable.                                                               |
| provisioning | Being created or booted. About a minute.                                        |
| suspended    | Paused. Compute is stopped; the disk stays.                                     |
| waking       | Coming back from a pause.                                                       |
| deep sleep   | Suspended over 14 days: the disk is parked as a snapshot. Waking takes minutes. |
| resizing     | Changing size. Returns to running.                                              |
| migrating    | Moving to another region; see [Regions](#regions).                              |
| degraded     | The box stopped reporting; it reboots itself.                                   |

## Pause and resume [#pause-and-resume]

```bash
prized box pause mango
prized box resume mango --wait
```

The disk always survives a pause: files, tools, and git state stay put, and billing drops to the sleep rate at once. Running processes depend on the size:

| Size               | On pause                                                                                                    |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Nano through Small | **Memory snapshot** (hibernate). Processes, tmux sessions, and half-finished builds resume where they were. |
| Medium and larger  | **Clean stop.** Files survive; processes restart on resume.                                                 |

`prized ssh` wakes a suspended box on connect. A box's [desktop](https://prized.dev/docs/desktop) follows the same table.

## Auto-pause [#auto-pause]

Set per box: **Auto-pause** on the box's dashboard page (30 minutes to 24 hours), `prized box auto-pause mango 2h` (up to 7 days), or `prized box new --auto-pause 45m`. The box pauses itself once nothing has used it for that long. Off by default, and a plan feature: boxes on the [free credit](https://prized.dev/docs/billing#free-credit) never pause themselves, and setting a window on one answers `409 trial_no_auto_pause`.

* **Counts as use:** typing or output in any terminal session, sustained CPU (builds, agents, test loops), sustained network traffic. A forgotten shell prompt does not.
* **The 30 minute floor** is how long the box waits before calling itself idle; the box page shows the idle time so far.
* **It is exactly a pause:** sleep rate, disk kept, processes per the size table. The event list shows it as `reconciler:auto_pause`.
* **A workspace policy can cap the window** ([auto-pause floor](https://prized.dev/docs/teams#policies)); [quiet hours](https://prized.dev/docs/teams#quiet-hours) pause the whole workspace nightly.
* **Not on the free credit.** A box running on it is never auto-paused, floor or no floor — a first sync or a long build looks idle to the box and pausing one mid-work costs more than the credit it saves. Pause it yourself from the dashboard or `prized box pause` when you are done.

## Pause deadline [#pause-deadline]

```bash
prized box new ci-run --ttl 2h          # pauses two hours from now
prized box extend mango --ttl 12h       # set, or push back, the deadline
prized box extend mango --no-deadline
```

The other pause rule: a time. The box pauses itself then, busy or idle (a resize or move in flight finishes first). Set it with `--ttl` at create, `prized box extend` later, or **Pause at** on the box page; 5 minutes to 30 days.

* **One pause, not a schedule.** The deadline clears when it fires or when the box wakes.
* **Extending replaces.** A new `--ttl` counts from now; `--no-deadline` removes it.
* **It needs a running box.** Setting one on a paused box is refused; clearing is always allowed.
* **It stacks with auto-pause.** Whichever comes first pauses the box.
* **It is exactly a pause**, shown in the event list as `reconciler:pause_deadline`.

## Resize [#resize]

```bash
prized box resize mango Medium
```

The box stops, changes size, and starts again, files intact, metering at the new rate from that moment. Any size your balance can keep running is allowed.

* **Sizing up** grows the disk during the same restart. Rarely a just-grown disk must wait about six hours before growing again; the resize still lands and the space appears on the next restart.
* **Sizing down** keeps the disk you have (disks never shrink), which keeps costing its own sleep rate.
* **A box mid-change cannot be resized**: refused while creating, resizing, or moving. Suspended boxes resize fine and take the new size when they next start.
* **A box with a bigger disk than its size normally has** is priced with that disk, so the resize check quotes what you will actually pay.

## Regions [#regions]

New boxes are created in US West (Oregon); boxes can also run in US West (N. California). Move with the box page's **Move region** button or `prized box move mango california` (`prized box new --region california` creates in Oregon and moves after the first boot).

* **The box stays up while the disk copies**, then goes offline for a few minutes and comes back in the new region with its name, files, tools, vars, and secrets.
* **The public IP changes**; `prized ssh` follows the box.
* **Metering continues at the normal rate** throughout, and a size costs the same in both regions.
* **Only a running box moves**, one move at a time.
* **A move that cannot finish** leaves the box in its original region on its original disk.
* **Four moves per box in 24 hours**, counting only moves that ran; moving needs a funded balance.

## Snapshots [#snapshots]

Snapshot a box's disk without stopping it, restore into a new box, fork a running box, save named templates, or set a schedule. Take one before risky changes. See [Snapshots](https://prized.dev/docs/snapshots).

## Infinite storage (alpha) [#infinite-storage-alpha]

Some boxes keep their files in a storage pool that grows on demand instead of on a fixed disk. A box like this shows an **Alpha - infinite storage** label and reports how much it is using rather than a disk size. You write to it exactly like a local disk: the same `/home`, the same Docker, the same tools, with space added behind the scenes as you fill it.

The alpha is opt-in and enabled per workspace by the Prized team. While a box is on it, disk snapshots, forks, templates, and region moves are paused for that box; everything else works as usual. Ask us if you want a box on it.

If the storage service on such a box fails, the box reboots itself and is back in about a minute. Files you saved are safe; writes from the last few seconds before the failure can be lost, as on a laptop that loses power.

## Environments [#environments]

An environment is what a new box inherits: repos, a setup script, env vars, secret files, and which credentials the box may receive. Pick one at create time or mark a default; every save is a new version, and a running box keeps its version until you upgrade it. See [Environments](https://prized.dev/docs/environments).

## Several boxes [#several-boxes]

Every box has a hostname: a fruit name unless you pick one (lowercase letters, digits, and hyphens, up to 32 characters). `prized ssh mango` connects to any box.

The box `prized setup` connected first (or `prized login`, when your account had exactly one) is the **default box**: what every command means when you name none. Any other box is reachable by name as it is; connecting it with `--box` gives it a config and a daemon of its own, for sync, mirrored ports and every other command.

```bash
prized setup --box mango            # connect a second box: its own config and daemon, then the usual setup steps
prized --box mango status           # aim any command at it
PRIZED_BOX=mango prized sync ls     # the same from the environment
```

* **Adding a box.** `prized setup --box mango` writes `boxes/mango.toml`, starts its daemon, and runs the normal setup flow; `prized init --box mango` only connects. With no default box yet, either makes the box the default.
* **Aiming commands.** `--box NAME` (or `PRIZED_BOX`) works on every command, by hostname or, for `setup` and `init`, box id. `--config PATH` overrides everything and is the escape hatch, not the everyday way.
* **Changing the default.** `prized init --force --box mango` rewrites the default config (backed up first) and restarts the default daemon. A box with its own file is refused; `prized --box mango daemon uninstall` and delete `boxes/mango.toml` first.
* **Same-named projects.** Two boxes cannot sync a project under one name; the second `prized sync add` asks for `--name`.
* **The same port on two boxes** shows as `conflicted` in `prized ports ls`; toggle it off on one box, or list it under `[ports].never` in that box's config.

| For a box named `mango` | Where                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| Config                  | `~/.config/prized/boxes/mango.toml`, the same schema as `config.toml`                                  |
| Agent token             | `~/.config/prized/boxes/mango.token`                                                                   |
| WireGuard key           | `~/.config/prized/wg-mango.key`                                                                        |
| Daemon socket and state | `~/Library/Application Support/prized/boxes/mango/prizedd.sock` (macOS and Linux)                      |
| Service                 | launchd `com.hudware.prizedd.mango`, systemd `prizedd-mango.service`, or the `PrizedDaemon-mango` task |
| Log                     | `prizedd-mango.log` in the usual [log folder](https://prized.dev/docs/cli#files)                                         |

On Windows these sit under `%LOCALAPPDATA%\Prized\boxes\`.

## Delete [#delete]

```bash
prized box delete mango        # asks you to type the name; -y skips the prompt
```

> Deleting a box terminates the machine and erases its disk. Anything you synced is already on your machine.

The disk's last state is kept for 7 days under **Recently deleted** on the Snapshots page; restoring it undoes the delete. See [Data retention](https://prized.dev/docs/data-retention), including zero data retention, which turns the undo window off.