CPU sandboxes API

A CPU sandbox is a Linux workspace you can start when you need to run code. Each user currently has one primary sandbox. Use your API key with https://api.dexto.ai; the dashboard’s visual desktop is not a separate public API resource.

Get or create your sandbox

POST /v1/sandboxes

curl -X POST https://api.dexto.ai/v1/sandboxes \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID"

The response has an id, primary, and status. The first call creates a paused sandbox and returns 201; later calls return the same primary sandbox with 200. Save its id for the remaining calls. GET /v1/sandboxes lists your sandboxes, and GET /v1/sandboxes/{sandbox_id} reads one.

Start, pause, or delete

POST /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"

Use POST /v1/sandboxes/{sandbox_id}/pause to stop charging for active compute while retaining its workspace. Create, start, pause, and delete require an Idempotency-Key; retry the same lifecycle request with the same key if the response is lost.

Deleting the primary sandbox permanently removes its workspace. To confirm, call DELETE /v1/sandboxes/{sandbox_id}?delete_primary=true with an Idempotency-Key. Without the confirmation query, the API returns 409.

Run a command

POST /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

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

See /v1/openapi.json for the complete request and response schemas, errors, and rate limits.