---
title: "Control API Code Sandboxes | Tarka Docs"
description: "Manage Tarka Code Sandbox templates, instances, execution, idempotency, and output retention through the Control API."
url: "https://tarkahq.com/docs/control-api/sandboxes/"
---

Available Control API · Sandboxes

# Code Sandbox lifecycle

Build dependency-pinned templates, start short-lived Python or Node.js runtimes, execute source, and retrieve encrypted retained output.

Authentication

## Use an account token or a sandbox-scoped key

An approved account token may call SandboxService for an entitled organization. Server-side automation may instead use an active `tk_live_` key with the `sandboxes` scope; that key is locked to its creation organization.

**Organization binding is enforced.**

A sandbox key cannot substitute another `org_id`. Account-token mutations require owner, admin, or operator. Key-based calls inherit the creating account and still require active platform, product, membership, organization, and key state.

## Review and accept a compute quote

The console obtains a five-minute quote before starting a new sandbox. API clients can POST `product: "sandboxes"`, location and matching runtime/resources to `/orgs/{org_id}/compute-quotes`, then include `accepted_quote_id` on creation. A sandbox API key can quote only sandboxes in its own organization. Quote retrieval does not reserve credit.

Omitted location remains `eu-1`. Legacy EU API requests remain compatible; choose `us-1` explicitly for US East. Built-in Python and Node.js runtimes support metered HTTPS with an accepted network allowance. See [billing, expiry and reservation errors](https://tarkahq.com/docs/control-api/billing-quotes/).

Start runtime

## Create from a ready template

Built-in aliases include supported Python and Node.js versions. A sandbox lifetime defaults to 300 seconds and is constrained to 30–300 seconds.

Create sandbox `idempotent`

```
CREATE_KEY=$(openssl rand -hex 16)  # reuse it only to retry this create
curl -X POST "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes" \
  -H "Authorization: Bearer $TARKA_SANDBOX_KEY" \
  -H "Idempotency-Key: $CREATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template":"python-3.13",
    "timeout_seconds":300
  }'
```

Creation returns a `CodeSandbox` containing its ID, organization, template and revision IDs, runtime, lifecycle status, expiration, and timestamps. Poll `GetSandbox` until `READY` before execution.

Execute

## Run one bounded source payload

Source is required and capped at 128 KiB. Stdin is optional and capped at 64 KiB. Execution timeout defaults to 10 seconds and must be 1–30 seconds.

Execute source `POST :execute`

```
RUN_KEY=$(openssl rand -hex 16)  # a new key for every execution
curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/sandboxes/${SANDBOX_ID}:execute" \
  -H "Authorization: Bearer $TARKA_SANDBOX_KEY" \
  -H "Idempotency-Key: $RUN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code":"print(input().upper())",
    "stdin":"ready",
    "timeout_seconds":10
  }'
```

**One execution at a time**

A busy sandbox rejects concurrent work rather than multiplexing source into one runtime.

**Terminal state**

`SUCCEEDED`, `FAILED`, `TIMED_OUT`, or `CANCELLED` includes exit and error metadata.

**Output retention**

Stdout and stderr are encrypted at rest and retained for 15 minutes, then omitted from later reads.

Custom templates

## Build one immutable dependency revision

Select one ready built-in base and provide exactly one supported manifest: `requirements_txt`, `pyproject_toml`, or `package_json`. Aliases are organization-scoped and URL-safe. Dependency inputs are normalized and pinned during the build.

**Deletion is retirement.**

A custom template can be deleted only when it has no active sandboxes. Built-in templates cannot be deleted by customers.

Safe retries

## Reuse a key only with identical content

Template creation, sandbox creation, and execution accept `idempotency_key` in JSON or `Idempotency-Key` metadata. The server retains the operation mapping for 24 hours. An identical retry returns the original resource; different content with the same key is rejected.

Use a new high-entropy key for each logical mutation. Retry transient transport, `429`, or `503` failures with the same key and exponential backoff.

Reference

## REST routes

Prefix every path with `https://tarka.rest/control/v1`. For the complete request and response walkthrough, see [Code Sandbox product documentation](https://tarkahq.com/docs/compute/sandboxes/code/).

| Method | Path | Ability |
| --- | --- | --- |
| `GET` | `/orgs/{org_id}/sandbox-templates` | List built-in and organization templates |
| `POST` | `/orgs/{org_id}/sandbox-templates` | Build a custom immutable dependency revision |
| `GET` | `/orgs/{org_id}/sandbox-templates/{template_id}` | Read template state |
| `DELETE` | `/orgs/{org_id}/sandbox-templates/{template_id}` | Retire an unused custom template |
| `GET` | `/orgs/{org_id}/sandboxes` | List non-deleted sandboxes |
| `POST` | `/orgs/{org_id}/sandboxes` | Start a sandbox |
| `GET` | `/orgs/{org_id}/sandboxes/{sandbox_id}` | Read sandbox state |
| `DELETE` | `/orgs/{org_id}/sandboxes/{sandbox_id}` | Idempotently stop and delete a sandbox |
| `POST` | `/orgs/{org_id}/sandboxes/{sandbox_id}:execute` | Execute one source payload |
| `GET` | `/orgs/{org_id}/sandboxes/{sandbox_id}/executions/{execution_id}` | Read execution state and retained output |