Architecture - ascii

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

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.