--- title: "Code Sandboxes API | Tarka Docs" description: "Create dependency templates, start isolated Python or Node.js sandboxes, and execute source code with the Tarka API." url: "https://tarkahq.com/docs/compute/sandboxes/code/" --- Available Compute · Sandboxes # Code Sandboxes Execute Python or Node.js source in a short-lived isolated runtime, collect its output, and terminate it when finished. Provisioning and management **Use the console or the Control API.** Create templates and Code Sandboxes in the console or through the Control API. Both surfaces expose the same organization resources, status, limits, and lifecycle. [Open console](https://tarkahq.com/console) [Control API overview](https://tarkahq.com/docs/control-api/sandboxes/) On this page [Quickstart](https://tarkahq.com/docs/compute/sandboxes/code/#quickstart) [Templates](https://tarkahq.com/docs/compute/sandboxes/code/#templates) [Custom templates](https://tarkahq.com/docs/compute/sandboxes/code/#custom-templates) [Run code](https://tarkahq.com/docs/compute/sandboxes/code/#executions) [Lifecycle](https://tarkahq.com/docs/compute/sandboxes/code/#lifecycle) [API reference](https://tarkahq.com/docs/compute/sandboxes/code/#api-reference) [Capacity](https://tarkahq.com/docs/compute/sandboxes/code/#capacity) [Product boundaries](https://tarkahq.com/docs/compute/sandboxes/code/#boundaries) **One narrow job.** Code Sandboxes execute source code. They are not containers, remote development machines, job runners, or browser sessions. The API intentionally does not expose a shell, subprocesses, SSH, ports, Docker images, background services, git, or persistent volumes. Mental model ## Template, sandbox, execution Choose a prepared runtime, create a sandbox, then execute one source program at a time. 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. Quickstart ## Run Python in three stages Use a Tarka API key and your organization ID. API keys are available in the[Tarka console](https://tarkahq.com/console). **Authentication** Create a key with the `sandboxes` scope, then send`Authorization: Bearer tk_live_...` on every request. Keep API keys on your server; never ship them in browser code. 1 ### Create a sandbox Built-in templates are ready to use without a custom dependency build. Request `POST /sandboxes` ``` curl -X POST "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes" \ -H "Authorization: Bearer $TARKA_API_KEY" \ -H "Idempotency-Key: create-demo-1" \ -H "Content-Type: application/json" \ -d '{ "template": "python-3.12", "timeout_seconds": 300 }' ``` Response · 200 `application/json` ``` { "id": "sbx_01K3H9Q2F7M6R5N4P3T2V1W0XY", "status": "CODE_SANDBOX_STATUS_STARTING", "template_alias": "python-3.12", "runtime": "SANDBOX_RUNTIME_PYTHON", "timeout_seconds": 300, "expires_at": "2026-08-20T14:35:00Z" } ``` Creation is asynchronous. Poll the sandbox resource until its status is`CODE_SANDBOX_STATUS_READY` before executing code. Poll readiness `GET /sandboxes/{sandbox_id}` ``` curl \ "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes/$SANDBOX_ID" \ -H "Authorization: Bearer $TARKA_API_KEY" ``` 2 ### Execute source code The template selects the runtime, so an execution only needs source code and its optional stdin. Save the sandbox `id` as `SANDBOX_ID`. Python `POST /sandboxes/:execute` ``` 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": "values = [21, 34, 55]\nprint(sum(values))", "stdin": "", "timeout_seconds": 10 }' ``` Response · 200 `application/json` ``` { "id": "exec_01K3H9T4CX9J1W8M7N6P5Q4RST", "status": "EXECUTION_STATUS_SUCCEEDED", "stdout": "110\n", "stderr": "", "exit_code": 0, "duration_ms": 47 } ``` 3 ### Terminate the sandbox Sandboxes expire automatically. Terminate one as soon as you are finished to release its capacity immediately. Request `DELETE /sandboxes/{sandbox_id}` ``` curl -X DELETE \ "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes/$SANDBOX_ID" \ -H "Authorization: Bearer $TARKA_API_KEY" ``` Templates ## Versioned runtime environments A template is a versioned runtime definition. Built-in templates contain the language runtime and its standard tooling. | Alias | Runtime | Custom manifest | | --- | --- | --- | | `python-3.12` | Python 3.12 | requirements.txt or pyproject.toml | | `python-3.13` | Python 3.13 | requirements.txt or pyproject.toml | | `node-22` | Node.js 22 | package.json | | `node-24` | Node.js 24 | package.json | **Pin the alias.** Runtime versions are part of the template name. Use a complete alias such as`python-3.12` instead of relying on a moving `python` alias. Custom templates ## Preinstall project dependencies Derive from a built-in template and attach exactly one dependency manifest. Tarka validates and prepares the dependencies before the template becomes available for sandbox creation. **Python + pip** `requirements.txt` Use pinned versions for repeatable builds. **Python + uv** `pyproject.toml` uv resolves dependencies; the project itself is not installed. **Node.js** `package.json` Declare runtime dependencies under `dependencies`. requirements.txt `POST /sandbox-templates` ``` 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" }' ``` Response · 200 `application/json` ``` { "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 Python `pyproject.toml + uv` ``` { "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" } ``` Node.js `package.json` ``` { "alias": "node-validation", "display_name": "Node validation", "base_template_alias": "node-22", "package_json": "{\"private\":true,\"dependencies\":{\"zod\":\"3.25.76\"}}" } ``` **A template is not an image recipe.** Custom templates cannot run build scripts supplied by the caller, install operating system packages, copy arbitrary files, set a startup command, or keep a process warm. Only dependency manifests are accepted. URL, git, local-path, editable, custom-index, workspace, and lifecycle-script dependency sources are rejected. Python packages must have wheels and Node installation always uses `--ignore-scripts`. ### Build states A custom template moves through the `BUILDING`, `READY`, or`FAILED` enum states. Poll the template resource until it returns`SANDBOX_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. Executions ## Source in, result out Every call runs one source program with the sandbox's selected runtime. There is no command or executable field. `code` string · required Python or JavaScript source code to execute. `stdin` string · optional Text made available on standard input. `timeout_seconds` integer · optional 1–30 seconds; defaults to 10. ### Node.js example with JSON stdin Node.js `POST /sandboxes/:execute` ``` 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. Lifecycle ## Short-lived by design starting *→* ready *→* busy *→* ready *→* stopped 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. **Fixed limits** Sandboxes use 1 vCPU and 1 GiB. Lifetime is 30–300 seconds and defaults to 300. The default organization quota is two active sandboxes, 20 creates/hour, 30 executions/hour, ten custom templates, and five builds/day. REST API ## Endpoint reference All routes are scoped to an organization and use the Tarka control-plane base URL. Base URL `https://tarka.rest/control/v1` **REST and gRPC use the same contract.** Native gRPC is served at `grpc.tarka.rest:443`. The authoritative protobufs and OpenAPI contracts are public in the contract-only[Tarka API repository](https://github.com/TarkaHQ/api). Pin a tagged release and use Buf or protoc to generate a client for your language. The repository intentionally contains no generated SDK or service implementation. REST is generated from the same service annotations. GET `/orgs/{org_id}/sandbox-templates` List built-in and custom templates POST `/orgs/{org_id}/sandbox-templates` Create a custom dependency template GET `/orgs/{org_id}/sandbox-templates/{template_id}` Read template build status DELETE `/orgs/{org_id}/sandbox-templates/{template_id}` Delete a custom template GET `/orgs/{org_id}/sandboxes` List active and recent code sandboxes POST `/orgs/{org_id}/sandboxes` Create a code sandbox GET `/orgs/{org_id}/sandboxes/{sandbox_id}` Read sandbox state POST `/orgs/{org_id}/sandboxes/{sandbox_id}:execute` Run source code GET `/orgs/{org_id}/sandboxes/{sandbox_id}/executions/{execution_id}` Read retained execution output DELETE `/orgs/{org_id}/sandboxes/{sandbox_id}` Terminate a sandbox ## 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. Boundaries ## What belongs somewhere else The narrow API keeps code execution predictable and easier to isolate. **Code Sandboxes** Short Python or JavaScript programs with captured input and output. **Job Runners** Long-running commands, batch workloads, repository checkout, and generated artifacts. **Agent Hosts** Persistent processes, services, ports, state, tools, and private network access. **Not part of the Code Sandbox API** Shell commands and child processes, Dockerfiles and arbitrary images, OS packages, runtime dependency installation, background processes, HTTP servers, inbound ports, SSH, browser automation, git operations, file upload and download APIs, durable storage, and GPU execution. Next step **Create an API key with the sandboxes scope.** [Open console](https://tarkahq.com/console)