Skip to content

Run code in a cloud sandbox

Give an AI agent a Linux sandbox in the cloud: create it, run commands and tests, move files in and out, and pause it when done. CLI, MCP and API steps.

A Dexto sandbox is a Linux workspace (4 vCPU, 8 GiB) in your Cloud project. An agent can run untrusted code, install packages or run a test suite there without touching your machine. It keeps its /workspace while paused and is charged per second only while running.

Create a sandbox, start it, then run commands in it:

Terminal window
SANDBOX=$(dexto cloud sandboxes create builder --json | jq -r '.id')
dexto cloud sandboxes start "$SANDBOX"
dexto cloud sandboxes exec "$SANDBOX" -- python3 --version

exec prints the command’s output and exits with the command’s own exit code, so an agent can branch on it. Put -- before a command that has options. A command waits up to 60 seconds by default; pass --timeout (up to 120000 ms) for a longer one, and --cwd to run it elsewhere than /workspace.

Write a file and run it:

Terminal window
printf 'print(sum(range(10)))\n' | dexto cloud sandboxes write "$SANDBOX" /workspace/sum.py
dexto cloud sandboxes exec "$SANDBOX" -- python3 /workspace/sum.py
dexto cloud sandboxes cat "$SANDBOX" /workspace/sum.py

Move files between the sandbox and your project’s files:

Terminal window
FILE_ID=$(dexto cloud files upload ./data.csv data/data.csv --json | jq -r '.id')
dexto cloud sandboxes import "$SANDBOX" "$FILE_ID"
dexto cloud sandboxes export "$SANDBOX" /workspace/report.txt reports/report.txt

Pause it when you are done; the workspace stays. Deleting removes the workspace too, and needs your person’s agreement:

Terminal window
dexto cloud sandboxes pause "$SANDBOX"
dexto cloud sandboxes delete "$SANDBOX" # exit 4: ask your person
dexto cloud sandboxes delete "$SANDBOX" --yes # only after they agree

create is safe to repeat: a name that already exists returns the same sandbox.

Over MCP a client can see sandboxes and read their files, but not run commands in them: dexto_cloud_sandboxes_list, dexto_cloud_sandboxes_get, dexto_cloud_sandboxes_ls and dexto_cloud_sandboxes_cat. Creating, starting and running commands stay with the CLI and the API, because each one starts paid compute. To let a Dexto agent run code itself, give it a sandbox tool (below).

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":"python3 --version","cwd":"/workspace","timeout_ms":60000}'

The response has exit_code, stdout and stderr. Create and start need an Idempotency-Key header. See the Sandboxes API.

An agent you build on Dexto can get a sandbox of its own for each session:

Terminal window
dexto cloud agents create --name "Builder" \
--instructions "Run the code you are given and report the output." \
--tool sandbox

The agent starts and pauses its sandbox itself. See Build agents by capability.

A running sandbox is charged per second from your organization’s credits; an idle one is paused for you. Without credits, start fails with insufficient_credits and nothing runs. A file read or write through cat and write is up to 1 MiB of UTF-8 text; use import and export for anything else.