> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariana.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Instant cloud development sandboxes you can SSH into, run AI agents on, and snapshot at will.

Box gives you on-demand Linux VMs in seconds. Each box is a fully isolated machine pre-loaded with the tools you need to code, test, or run AI agents — accessible from your terminal or the web dashboard.

## Key concepts

| Concept            | What it means                                                               |
| ------------------ | --------------------------------------------------------------------------- |
| **Box**            | A single Linux VM with a unique ID like `bx_f7k2q9hd`                       |
| **TTL**            | How long the box lives before it auto-deletes (default 1 hour, max 30 days) |
| **Snapshot**       | A point-in-time image of a box, used for stop/resume and fork               |
| **Credit seconds** | The billing unit — seconds your box is in an active state                   |

## Box lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> provisioning: box new
    provisioning --> provisioned: VM reserved
    provisioned --> ready: setup complete
    ready --> archiving: box stop
    archiving --> archived: snapshot saved
    archived --> ready: box resume
    ready --> [*]: box delete
```

**Billable states:** `provisioned`, `cloning`, `ready`, `idle`, `running`\
**Not billed:** `archived` (stopped), `provisioning`, `archiving`, `error`

## Box IDs

Every box gets a unique public ID in the format `bx_<8 chars>` (e.g. `bx_f7k2q9hd`). Use this ID with every CLI command. Internal UUIDs are never exposed.