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.

Built-in base images — first-party, supported by us:

These are the fastest images to start with. Because they're first-party and kept warm on the hosts, a sandbox on a built-in base boots immediately — no image pull. A custom template you build is slower the first time it's used on a host, since that host has to fetch it before the first boot; subsequent boots are cached and fast. Start from a built-in base and layer your dependencies via a template when you need speed on the first launch.

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, and 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
Copy
1{ "status": "success", "data": { } }

status is success, fail (input/validation problem), or error (server-side). List endpoints page their results. See the REST API overview.