AvailableControl 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.

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 sandboxidempotent

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 sourcePOST :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.

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