Sandboxes API
Create named sandboxes in a Cloud project, run commands, and work with files through /v1.A sandbox is a Linux workspace you start when you need to run code. Sandboxes belong to your API
key’s Cloud project: a project can hold many, each with a name that is unique in the project. Use
your API key with https://api.dexto.ai. A key sees only its own project’s sandboxes.
Create a sandbox
Section titled “Create a sandbox”/v1/sandboxes curl -X POST https://api.dexto.ai/v1/sandboxes \ -H "Authorization: Bearer $DEXTO_API_KEY" \ -H "Idempotency-Key: $REQUEST_ID" \ -H "Content-Type: application/json" \ -d '{"name":"builder","size":"large"}'| Size | Resources |
|---|---|
large | 4 vCPU and 8 GiB RAM |
large is the only size for now; more sizes will follow.
Names are 1-63 lowercase letters, digits and hyphens. The response has an id, name, size and
status, and returns 201 with a new sandbox that has not started. Creating a name that already
exists returns that sandbox with 200, so retrying is safe. GET /v1/sandboxes lists the project’s sandboxes (limit, and after set to the previous page’s next_after), and
GET /v1/sandboxes/{sandbox_id} reads one.
status is not_started, running, paused or terminated. A terminated sandbox has lost its
workspace; starting it again begins with an empty one.
Start, pause, or delete
Section titled “Start, pause, or delete”/v1/sandboxes/{sandbox_id}/start curl -X POST "https://api.dexto.ai/v1/sandboxes/$SANDBOX_ID/start" \ -H "Authorization: Bearer $DEXTO_API_KEY" \ -H "Idempotency-Key: $REQUEST_ID"A running sandbox is charged per second from your organization’s credits, at its size’s rate.
Without enough credits a start returns 402 with insufficient_credits; past a monthly spend
limit on the project or your key, it returns 402 with spend_limit_reached. Use
POST /v1/sandboxes/{sandbox_id}/pause to stop charging while keeping its workspace; an idle
sandbox is also paused for you. Create, start, pause, and delete require an Idempotency-Key;
retry the same lifecycle request with the same key if the response is lost.
DELETE /v1/sandboxes/{sandbox_id} stops the sandbox and deletes it with its workspace, and frees
its name. Sandboxes of an archived Cloud project are paused and cannot start until the project is
restored.
Run a command
Section titled “Run a command”/v1/sandboxes/{sandbox_id}/processes curl -X POST "https://api.dexto.ai/v1/sandboxes/$SANDBOX_ID/processes" \ -H "Authorization: Bearer $DEXTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"command":"pwd","cwd":"/workspace","timeout_ms":60000}'The response contains exit_code, stdout, and stderr. Commands run only while the sandbox is
running. If a command response is lost and you retry, the command may run twice; process calls
do not have lifecycle-style replay protection.
Work with files
Section titled “Work with files”All file paths must stay under /workspace, and the sandbox must already be running. These are
JSON POST operations:
| Path | Request fields | Result |
|---|---|---|
/v1/sandboxes/{sandbox_id}/files/list | path, depth | data array of files |
/v1/sandboxes/{sandbox_id}/files/read | path, optional max_bytes | UTF-8 content, sha256 |
/v1/sandboxes/{sandbox_id}/files/write | path, content, create_directories | bytes_written, sha256 |
/v1/sandboxes/{sandbox_id}/files/delete | path | { "deleted": true } |
For example:
curl -X POST "https://api.dexto.ai/v1/sandboxes/$SANDBOX_ID/files/read" \ -H "Authorization: Bearer $DEXTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"path":"/workspace/README.md"}'Copy project files in and out
Section titled “Copy project files in and out”A sandbox’s /workspace is its own. To work on your project’s files, copy them in;
to keep what the sandbox made, save it as a file. Both need a running sandbox and are free; the
copy is checked against each file’s SHA-256.
| Path | Request fields | Result |
|---|---|---|
/v1/sandboxes/{sandbox_id}/files/import | directory, and file_ids (up to 100) or prefix | data of copied files |
/v1/sandboxes/{sandbox_id}/files/export | path (sandbox), file_path, overwrite, content_type | the saved file |
An imported file lands at <directory>/<its path>, or at its path after the prefix when you copy a
prefix, replacing what is there:
curl -X POST "https://api.dexto.ai/v1/sandboxes/$SANDBOX_ID/files/import" \ -H "Authorization: Bearer $DEXTO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prefix":"data/","directory":"/workspace/data"}'An export is an upload of up to 5 GiB: a taken file_path is 409 unless overwrite is true,
and it is refused with 402 without credits or at a spend limit. Its storage is charged like any
file.
Agents you build with the Agents API can use a sandbox through the sandbox tool.
See /v1/openapi.json for the complete request and
response schemas, errors, and rate limits.