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.
With the CLI
Section titled “With the CLI”Create a sandbox, start it, then run commands in it:
SANDBOX=$(dexto cloud sandboxes create builder --json | jq -r '.id')dexto cloud sandboxes start "$SANDBOX"dexto cloud sandboxes exec "$SANDBOX" -- python3 --versionexec 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:
printf 'print(sum(range(10)))\n' | dexto cloud sandboxes write "$SANDBOX" /workspace/sum.pydexto cloud sandboxes exec "$SANDBOX" -- python3 /workspace/sum.pydexto cloud sandboxes cat "$SANDBOX" /workspace/sum.pyMove files between the sandbox and your project’s files:
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.txtPause it when you are done; the workspace stays. Deleting removes the workspace too, and needs your person’s agreement:
dexto cloud sandboxes pause "$SANDBOX"dexto cloud sandboxes delete "$SANDBOX" # exit 4: ask your persondexto cloud sandboxes delete "$SANDBOX" --yes # only after they agreecreate is safe to repeat: a name that already exists returns the same sandbox.
With MCP
Section titled “With MCP”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).
With the HTTP API
Section titled “With the HTTP API”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.
Give a Dexto agent its own sandbox
Section titled “Give a Dexto agent its own sandbox”An agent you build on Dexto can get a sandbox of its own for each session:
dexto cloud agents create --name "Builder" \ --instructions "Run the code you are given and report the output." \ --tool sandboxThe agent starts and pauses its sandbox itself. See Build agents by capability.
Cost and limits
Section titled “Cost and limits”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.