Code Sandboxes

1. 01
   Choose a template

   Use a built-in runtime or a custom dependency template.

2. 02
   Create a sandbox

   Receive an isolated runtime with a fixed expiry.

3. 03
   Run source code

   Send code and stdin; receive stdout, stderr, and exit status.

curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandbox-templates" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "python-data",
    "display_name": "Python data",
    "base_template_alias": "python-3.12",
    "requirements_txt": "numpy==2.2.6\npandas==2.3.1\n",
    "idempotency_key": "template-python-data-v1"
  }'

{
  "id": "stpl_01K3H8YD7G4M2P9R8S7T6V5WXY",
  "alias": "python-data",
  "base_template_alias": "python-3.12",
  "status": "SANDBOX_TEMPLATE_STATUS_BUILDING",
  "dependency_file_type": "requirements.txt",
  "dependency_manifest_sha256": "d87d2b7...",
  "created_at": "2026-08-20T14:25:00Z"
}

Other supported manifests

{
  "alias": "python-analytics",
  "display_name": "Python analytics",
  "base_template_alias": "python-3.12",
  "pyproject_toml": "[project]\nname = \"analytics-runtime\"\nversion = \"0.1.0\"\ndependencies = [\"polars==1.32.0\"]\n"
}

{
  "alias": "node-validation",
  "display_name": "Node validation",
  "base_template_alias": "node-22",
  "package_json": "{\"private\":true,\"dependencies\":{\"zod\":\"3.25.76\"}}"
}

Build states

A custom template moves through the BUILDING, READY, orFAILED enum states. Poll the template resource until it returnsSANDBOX_TEMPLATE_STATUS_READY before creating a sandbox from its ID or alias. Submitting the same request with its idempotency key returns the same template resource instead of creating a duplicate.

Node.js example with JSON stdin

curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes/${SANDBOX_ID}:execute" \
  -H "Authorization: Bearer $TARKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "const fs = require(\"node:fs\"); const input = JSON.parse(fs.readFileSync(0, \"utf8\")); console.log(input.values.reduce((a, b) => a + b, 0));",
    "stdin": "{\"values\":[21,34,55]}",
    "timeout_seconds": 10
  }'

Execution semantics

• Executions in one sandbox are serialized; only one is active at a time.
• Each execution starts a fresh language process. In-memory variables do not carry over.
• The temporary workspace lasts only for the sandbox and is discarded when it stops.
• Child processes and runtime package installation are blocked; add dependencies to a template.
• Output is captured separately as stdout and stderr.
• A program error returns a completed execution with a non-zero exit_code.
• A timeout stops the execution without extending the sandbox expiry.
• Source and stdin are never stored. Encrypted output is retained for 15 minutes for idempotent reads.

A sandbox returns to ready after a successful or failed execution and may be used again until expires_at. Expiry and explicit deletion are terminal; create a new sandbox from the same template to continue.

Capacity and request rates

Approved organizations have no fixed count limit for active sandboxes, custom templates, or simultaneous template builds. Starts and builds need available shared capacity. Starting a sandbox also requires enough credit within your spending limits.

If all runtime capacity is in use, the API returns sandbox_cluster_capacity_unavailable with HTTP 429. Retry later or stop a sandbox you no longer need. Request-rate limits, execution timeouts, and runtime sizes still apply.