Skip to main content
Create a sandbox with one API call. Read the sandbox until its state is running. Delete it when you do not need it.

Write the code that creates and deletes a sandbox.

Before you start

  • Your workspace needs a plan or a trial. See Choose a plan or start a trial.
  • You need an API key with the sandboxes:write scope. A key with only sandboxes:read can read sandboxes and operations, but it cannot create or delete them. See API keys.
  • The examples use TypeScript with fetch. You can also use curl.

Create a sandbox

Send POST /v1/sandboxes with a size: small, medium, large, or xlarge. See the sizes. To make a sandbox from the files of another sandbox, see Fork a sandbox.
The API answers 202 with the sandbox in the creating state. The operation field holds the create operation:
The full object has more fields. See GET /v1/sandboxes/{id}.

Give environment variables and files

Send env and files in the create body, so that the sandbox is ready for your agent when it is running:
  • env has up to 100 variables. Each command, shell, and SSH session gets them. A name has letters, digits, and _, and does not start with a digit. A value has up to 4096 characters.
  • files has up to 20 files, with up to 65,536 characters of content in total. A path is absolute. encoding is utf8 (the default) or base64. A file in /home/user belongs to user.
  • The files are written one time, at the first start. A resume keeps your changes to them. The variables stay for each start.
To start with the files of a prepared sandbox, send template: the name or the ID of a template, or a share code from another workspace. See Save a sandbox as a template.
  • The API stores both encrypted and does not show them again.

Send an Idempotency-Key

Send a new Idempotency-Key header, such as a UUID, with each create. If the network fails, send the same request with the same key again. Within 24 hours, the API returns the first result and does not create a second sandbox.
  • The same key with a different body answers 409.
  • A create that answered 503 no_capacity keeps no result. A retry with the same key tries again.

When no host has room

A sandbox usually starts on a machine that is ready. If no ready machine is free but a host has room, the API still answers 202, and the sandbox is running when the next machine of its size is ready, a few seconds later. After many starts of one size in a short time, more machines of that size stay ready for one hour. If no host has room for the size, the API answers 503 at once:
Wait retryAfterSeconds, then try again or choose a different size. The Retry-After header has the same value. The sandbox in sandboxId is in the failed state. Its create operation has the error no_capacity. If the hosts are full when the new machine must start, the sandbox moves to failed within 60 seconds, and its create operation fails with no_capacity.

When a create is above a limit

The plan sets the sizes, the sandboxes at a time, and the starts each minute and each day. A create above a limit makes no sandbox:
  • 402 billing_required: the workspace has no plan and no trial, or a payment review is open.
  • 403 size_not_allowed: the trial does not include the size. Each paid plan includes each size.
  • 429 start_limit: too many sandboxes at a time, or too many starts. For too many starts, wait retryAfterSeconds, then try again.
Read your limits with GET /v1/limits. See the limits of each plan.

Answer within 1.5 seconds

Send "failFast": true in the body when your code cannot wait. The API then answers within 1.5 seconds. If it cannot answer in time, for example because a request with the same Idempotency-Key is still open, it answers 503 no_capacity with retryAfterSeconds.

Wait until the sandbox is running

The sandbox moves from creating to starting, then to running. Read it with GET /v1/sandboxes/{id} until the state is running. A key with sandboxes:read is enough.
To get a request when the sandbox is running, in place of reads, add a webhook endpoint. You can also read the operation with GET /v1/operations/{id}. Its status is pending, running, succeeded, or failed. A failed operation has an error with a code and a message.
Each API key can send 1,200 requests in one minute. Wait 1 second between two reads. After a 429, wait for the seconds in Retry-After.

Delete a sandbox

Send DELETE /v1/sandboxes/{id}. The API answers 202 with the sandbox in the deleting state and its delete operation. The sandbox then moves to deleted.
After the delete is complete, the next GET returns the sandbox one time with the state deleted. Each later GET answers 404. A second DELETE while the sandbox is deleting returns the same sandbox. When the delete is complete, dataExpiresAt shows the time of the delete. The saved files of the sandbox are deleted within 24 hours. Until then, you can read the files of its snapshots. After that, you cannot get them back.

Sandbox states