Sandboxes
A sandbox is a Linux machine of your own: a Firecracker microVM with its own kernel, memory, disk and network address. Code in one sandbox can't see another sandbox or the server it runs on. A sandbox is the right place for code you don't fully trust, such as code an AI model wrote or a customer uploaded.
What you choose at create#
POST /v2/sandboxes takes a SandboxCreate. Every field is optional:
| Field | What it sets |
|---|---|
vcpu |
Its vCPUs. |
memoryGB |
Its memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (1.5). |
diskGB |
Its disk in GB (1 GB is 1,024 MiB), to the MiB. |
image |
The image it boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
snapshot |
A snapshot it starts as: a copy of it running, at its sizes, in its project, with its secrets. |
name |
Its name, unique in its project. |
labels |
Labels to find it by. |
secrets |
The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it. |
maxCost |
The most it may cost in all, in US dollars ("5.00"): once it has cost that it pauses, and starts again only once its maxCost is raised (update); what a key's per-request and spend caps count. When omitted under a key with a per-request or spend cap, the most that key's caps leave. |
On the Pro plan, one sandbox has at most 8 vCPUs and 32 GiB of memory, and the account runs at most 100 vCPUs at once. See limits.
What runs in it#
The default image is a Linux system with Python and Node.js. Commands run as the user runtime in /workspace, with sudo and no password. Install anything with the system's package manager, or start from your own image or snapshot.
- Run commands with
POST /v2/sandboxes/{id}:exec, and long-running programs with it too, withwaitfalse. See commands and processes. - Read and write files with
GET /v2/sandboxes/{id}/filesandPUT /v2/sandboxes/{id}/files. See files. - Share a port at an HTTPS address with
POST /v2/sandboxes/{id}/previews. See previews.
What it costs#
A running sandbox is billed for the CPU it uses, $0.03 per busy vCPU-hour, at least 0.1 vCPU while it runs, and for the memory it holds, $0.008 per GB-hour. Its disk is $0.10 per GB-month while it runs. A paused sandbox is billed only for what it stores, $0.18 per GB-month. See pricing.
Find your sandboxes#
GET /v2/sandboxes returns the project's sandboxes, newest first. Filter it by state or by label. GET /v2/sandboxes/{id} returns one, by ID. A sandbox's state is one of starting, running, paused, deleted, error; see lifecycle.
Give this to your agent#
Paste this into your coding agent:
Read https://withruntime.com/docs/sandboxes.md and https://withruntime.com/docs/lifecycle.md, then explain to me how this project should use Runtime sandboxes: one per task or per user, what size, and when each is deleted.
This page as Markdown: https://withruntime.com/docs/sandboxes.md