Skip to content

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.

POST /v1/sandboxes
Terminal window
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"}'
SizeResources
large4 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.

POST /v1/sandboxes/{sandbox_id}/start
Terminal window
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.

POST /v1/sandboxes/{sandbox_id}/processes
Terminal window
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.

All file paths must stay under /workspace, and the sandbox must already be running. These are JSON POST operations:

PathRequest fieldsResult
/v1/sandboxes/{sandbox_id}/files/listpath, depthdata array of files
/v1/sandboxes/{sandbox_id}/files/readpath, optional max_bytesUTF-8 content, sha256
/v1/sandboxes/{sandbox_id}/files/writepath, content, create_directoriesbytes_written, sha256
/v1/sandboxes/{sandbox_id}/files/deletepath{ "deleted": true }

For example:

Terminal window
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"}'

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.

PathRequest fieldsResult
/v1/sandboxes/{sandbox_id}/files/importdirectory, and file_ids (up to 100) or prefixdata of copied files
/v1/sandboxes/{sandbox_id}/files/exportpath (sandbox), file_path, overwrite, content_typethe 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:

Terminal window
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.