Concepts
The vocabulary you'll meet across the API, SDK, and CLI.
Sandbox
A single Firecracker microVM — the unit you create, run commands in, and destroy. Each sandbox has a stable id, a name, a status, an IP on its network, and a shape and rootfs chosen at creation. A sandbox moves through a lifecycle:
creating → running → pausing → paused → resuming → running → destroying → destroyed
A sandbox can also enter error if something goes wrong, and forking while a clone is being made.
Shape
A compute size — the vCPU count and amount of RAM allocated to a sandbox. Shapes come from a fixed catalog (for example s-1vcpu-1gb). List them with GET /v1/shapes, the SDK, or createos sandbox shapes. You choose a shape at creation time.
Rootfs
The root filesystem image a sandbox boots from — a Linux userland such as Ubuntu, plus any preinstalled tooling. Built-in images come from a catalog (GET /v1/rootfs); you can also build your own with a template. Choose one with the rootfs field at creation, or accept the default.
Snapshot, pause, resume
A snapshot captures a sandbox's full state — memory and disk — to durable storage. Pause snapshots a running sandbox and tears down the live VM, so it stops consuming compute while keeping its identity, disks, networks, and environment. Resume restores a paused sandbox onto a host and starts it running again, typically in under a second.
Fork
Cloning a paused sandbox into a brand-new sandbox. The fork is a byte-identical copy of the snapshot but gets its own id, IP, placement, and bandwidth quota — the original is untouched. Forking is how you fan out many identical environments from one prepared base.
Network
A private overlay network that connects sandboxes. Sandboxes attached to the same network reach each other by name, and are isolated from sandboxes in other networks and from other tenants. Attach a sandbox at creation or live-attach it later.
Disk
An S3-compatible bucket registered as a mountable volume. A disk holds its bucket and endpoint configuration; credentials are encrypted at rest and never returned by the API. Disks can be attached to a running sandbox and detached live — the mount appears inside the guest within about a second.
Template
A custom rootfs built from a Dockerfile you submit. The build runs asynchronously and streams logs; once ready, the template can be used as the rootfs for new sandboxes. Templates let you bake dependencies in instead of installing them on every boot.
Ingress
An opt-in public HTTPS URL for a sandbox, so an HTTP service running inside it is reachable from the internet. Enable it at creation (ingress_enabled) or later. Certificates are managed for you.
Egress
The outbound traffic policy for a sandbox — an allowlist of hosts, IPs, or CIDRs (optionally with ports). When the allowlist is empty, all outbound traffic is allowed. Rules apply live, with no restart.
SSH gateway
A gateway (gateway.sb.createos.sh:2222) that accepts SSH connections authenticated by the public keys you attach to a sandbox. It's used for port forwarding (ssh -L) — the CLI's tunnel and shell --ssh commands ride on it.
Bandwidth
Each sandbox has a bandwidth quota. You can read current usage and recharge (top up) the quota. Networking pauses when the quota is exhausted until it's recharged.
Host and region
Sandboxes run on hosts, which may live in different regions. Placement is handled for you; resume and fork pick a fresh host automatically.
Response envelope
The REST API wraps every response in a JSend envelope:
JSON
status is success, fail (input/validation problem), or error (server-side). List endpoints page their results — see the REST API overview.