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:writescope. A key with onlysandboxes:readcan read sandboxes and operations, but it cannot create or delete them. See API keys. - The examples use TypeScript with
fetch. You can also usecurl.
Create a sandbox
SendPOST /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.
202 with the sandbox in the creating state. The operation field holds the create operation:
GET /v1/sandboxes/{id}.
Give environment variables and files
Sendenv and files in the create body, so that the sandbox is ready for your agent when it is running:
envhas 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.fileshas up to 20 files, with up to 65,536 characters of content in total. Apathis absolute.encodingisutf8(the default) orbase64. A file in/home/userbelongs touser.- The files are written one time, at the first start. A resume keeps your changes to them. The variables stay for each start.
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 newIdempotency-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_capacitykeeps 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 answers202, 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:
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, waitretryAfterSeconds, then try again.
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 fromcreating to starting, then to running. Read it with GET /v1/sandboxes/{id} until the state is running. A key with sandboxes:read is enough.
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
SendDELETE /v1/sandboxes/{id}. The API answers 202 with the sandbox in the deleting state and its delete operation. The sandbox then moves to deleted.
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.