Guides

Run code in a sandbox with the API

The same steps as sandscale sandbox start, exec and stop, from your own code.

You need a personal API key with the sandboxes:create and sandboxes:use permissions. Each request below is in the Sandboxes API reference, with every field.

API=https://api.sandscale.dev/api/v1/sandbox
AUTH="Authorization: Bearer $SANDSCALE_API_KEY"

1. See what you can start

curl "$API/launch-options" -H "$AUTH"

The answer lists the templates you can start, whether each can start now, and options such as port exposure when your organization allows them. Built-in templates have IDs such as builtin:python, builtin:node, builtin:go and builtin:base.

2. Start a sandbox

curl -X POST "$API/instances" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"template_id": "builtin:python", "ttl_seconds": 3600, "name": "try-it"}'

The answer is 201 with the sandbox’s id and status. Optional fields set the vCPU (cpu_count), memory (mem_mb), disk (disk_mb), environment variables (env), Vault secrets (secret_refs), labels and network mode. A request beyond your plan or your organization’s policy is refused before anything starts, for example with 429 quota_exceeded or 403 policy_denied. Sandboxes have no network unless your policy allows it.

3. Run a command

curl -X POST "$API/instances/$ID/exec" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"command": ["python3", "-c", "print(6 * 7)"], "timeout_sec": 60}'

The answer has exit_code, stdout, stderr, duration_ms, and timed_out and oom_killed flags. workdir, env and stdin are optional. Every run is recorded: GET /api/v1/sandbox/runs/{id} with the run_id returns its details and cost.

4. Move files in and out

Write a file. content is base64:

curl -X PUT "$API/instances/$ID/files" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"path\": \"/workspace/hello.py\", \"content\": \"$(printf 'print(\"hi\")' | base64)\"}"

Read a file, or list a directory:

curl "$API/instances/$ID/files?path=/workspace" -H "$AUTH"

To send a whole folder, POST /api/v1/sandbox/instances/{id}/project takes a gzip tar archive. GET .../project/changes returns what changed.

5. Stop it

curl -X DELETE "$API/instances/$ID" -H "$AUTH"

A sandbox also stops by itself when its ttl_seconds runs out. On Pro and up, POST /api/v1/sandbox/instances/{id}/snapshot saves its /workspace so you can start a new sandbox from it later with snapshot_id.