Sandboxes

A sandbox is an isolated container with a persistent /workspace directory. Your code or your agent runs commands in it (Python 3, bash, LibreOffice, Node 24, the usual data and document libraries, fonts with full Romanian coverage), writes results to /workspace/out and gets them back as artifacts: scanned, hashed and downloadable through a signed link. The workspace survives between execs until the sandbox is destroyed or expires.

Two backends share this API. v2 is the default since 18 October 2026: a long-lived pod with memory snapshots (pause/resume, fork, a persistent Python kernel, preview URLs), see Sandboxes v2. v1 (Cloud Run, the workspace restored per exec, plus POST /snapshot) stays available with backend: "v1". When you omit backend and v2 is not available for your key, the gateway falls back to v1; the backend field on every sandbox object says which one you got.

Every exec is metered; exec time is billed from the wallet afterwards (see Billing), so responses carry x-codai-cost-micro-usd: 0. Every route needs a codai_ key that reaches tool level l3_sandbox.

Security modelCopy Anchor Link

• gVisor isolation. Every sandbox runs under gVisor with its own kernel boundary: v2 as a dedicated pod on GKE, v1 on Cloud Run (gen2). The image filesystem is read-only for your code and only /workspace is writable.
• No network by default. With egress: { mode: 'none' } (the default) there is no route out at all: public IPs, private ranges and the metadata server are unreachable.
• Egress through an allowlisting proxy. { mode: 'allowlist', domains: [...] } (at most 20 host names, no IP literals, no internal suffixes) or { mode: 'preset', preset: 'pypi' | 'npm' } lets HTTPS reach only those hosts, through the codai egress proxy, which resolves DNS itself and logs every connection. This works on both backends; the proxy opens plain tunnels and never injects credentials.
• No secrets inside. No codai key, cloud credential or token is present in the sandbox; environment variables named CODAI_* or GOOGLE_* are rejected.
• Audited. Every create, exec, file transfer, artifact, snapshot and destroy is written to an append-only audit log; each exec returns a reproducibility receipt.
• Data stays in europe-west1 (x-codai-data-region).

LimitsCopy Anchor Link

LibreOffice converts every office format in the sandbox, for example soffice --headless --convert-to pdf --outdir /workspace/out report.docx (also .xlsx, .pptx, .odt, HTML and CSV). Every command runs under a small init that reaps background helper processes, and exit_code is the real exit status of your command.

ArtifactsCopy Anchor Link

GET /v1/sandboxes/{id}/artifacts collects every file under /workspace/out. Each artifact carries:

• mime, sniffed from the content (not from the file name);
• sha256 of the bytes;
• scan: the ClamAV verdict, clean, infected or error;
• url: a signed download link valid for 1 h, present only when scan is clean (expires_at says when it stops working).

POST /v1/sandboxes/run returns the artifacts directly in its result.

ReceiptsCopy Anchor Link

Every finished exec (the blocking result and the final exit stream event) includes a receipt: the image digest, the template, the SHA-256 of the inputs and of the command, every output file with its SHA-256 and size, and the workspace generation before and after. Store it next to the document you produced to prove what code made it, from which inputs.

StreamingCopy Anchor Link

Send Accept: text/event-stream to POST /v1/sandboxes/{id}/exec to receive data: frames as the command runs: start, then any number of stdout / stderr chunks (and truncated when a stream hits 1 MB), then exactly one exit (or error). Without that header the call blocks and returns one JSON result.

Idempotency-Key on exec and run replays the stored response of an earlier request with the same key for 24 h instead of running the command again.

Quickstart: a PDF with Romanian diacriticsCopy Anchor Link

One shot with POST /v1/sandboxes/run: the sandbox is created, the script runs, /workspace/out is collected and the sandbox is destroyed.

curl https://ai.codai.ro/v1/sandboxes/run \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: act-2026-10-16-001" \
  -d @- <<'JSON'
{
  "language": "python",
  "timeout_seconds": 120,
  "code": "import os\nfrom reportlab.lib.pagesizes import A4\nfrom reportlab.pdfbase import pdfmetrics\nfrom reportlab.pdfbase.ttfonts import TTFont\nfrom reportlab.pdfgen import canvas\n\npdfmetrics.registerFont(TTFont('DejaVu', '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf'))\nos.makedirs('/workspace/out', exist_ok=True)\nc = canvas.Canvas('/workspace/out/act.pdf', pagesize=A4)\nc.setFont('DejaVu', 14)\nc.drawString(72, 770, 'Act adițional nr. 1 la contractul de prestări servicii')\nc.drawString(72, 745, 'Părțile convin: ședința se mută în București, str. Ștefan cel Mare.')\nc.save()\nprint('ok')\n"
}
JSON

The answer is an exec result whose artifacts[0].url downloads act.pdf for one hour. The DejaVu Sans font embeds the full ă â î ș ț set, so the comma-below ș and ț render correctly.

SDKsCopy Anchor Link

import { Codai } from 'codai-sdk';

const client = new Codai({ apiKey: process.env.CODAI_API_KEY! });
const sb = await client.sandboxes.create({ ttl_seconds: 1800 });
await client.sandboxes.files.put(sb.id, 'in/date.csv', 'client,suma\nSC Exemplu SRL,1200\n');
for await (const ev of client.sandboxes.execStream(sb.id, {
  shell: 'python3 -c "import pandas as pd; print(pd.read_csv(\'in/date.csv\'))"',
})) {
  if (ev.type === 'stdout') process.stdout.write(ev.data);
  if (ev.type === 'exit') console.log('exit', ev.exit_code, ev.receipt.command_sha256);
}
const { data } = await client.sandboxes.artifacts(sb.id);
await client.sandboxes.delete(sb.id);

from codai import Codai

client = Codai(api_key="...")
sb = client.sandboxes.create(ttl_seconds=1800)
client.sandboxes.files.put(sb["id"], "in/date.csv", "client,suma\nSC Exemplu SRL,1200\n")
for ev in client.sandboxes.exec_stream(sb["id"], language="python", code="print(open('in/date.csv').read())"):
    if ev["type"] == "stdout":
        print(ev["data"], end="")
result = client.sandboxes.run(shell="weasyprint in/page.html out/page.pdf",
                              inputs=[{"path": "page.html", "url": "https://example.com/page.html"}])
client.sandboxes.delete(sb["id"])

The codai_sandbox chat toolCopy Anchor Link

Add { "type": "codai_sandbox" } to tools in POST /v1/chat/completions (optionally with egress and template) and the gateway does the rest server-side: it gives the model sandbox_bash, sandbox_python, sandbox_edit and sandbox_files, runs them in one sandbox per x-codai-session-id (lifetime 1 h, extended by every use) and, at the end, appends the artifacts to the final message as codai_sandbox.artifacts plus a markdown list with signed links. The key still needs tool level l3_sandbox.

curl https://ai.codai.ro/v1/chat/completions \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-codai-session-id: acte-firma-42" \
  -d '{"model":"codai","tools":[{"type":"codai_sandbox"}],
       "messages":[{"role":"user","content":"Fă-mi un PDF cu o hotărâre AGA pentru SC Exemplu SRL."}]}'

The built-in exec_python tool now runs on the same sandbox backend; it no longer executes code inside the gateway process.

Document skills (Claude Skills compatible)Copy Anchor Link

Anthropic's pre-built Agent Skills (docx, xlsx, pdf, pptx) need a first-party container that is not available on the clouds behind codai, so codai provides them on its own sandbox, for every model. Two equivalent forms:

{ "tools": [{ "type": "codai_sandbox", "skills": ["docx", "pdf"] }] }

{ "container": { "skills": [{ "type": "anthropic", "skill_id": "xlsx", "version": "latest" }] } }

Both work on /v1/chat/completions and /v1/messages. They enable the codai_sandbox tool and add a fixed guidance block for the requested skills (python-docx, openpyxl, reportlab/pypdf, python-pptx, weasyprint), so the model produces real files in /workspace/out and you get them as signed links. Custom skills (type: "custom") and container reuse (container.id) answer 400; use x-codai-session-id to keep one sandbox per conversation.

MCP toolsCopy Anchor Link

The codai MCP server (https://ai.codai.ro/mcp) exposes sandbox_create, sandbox_list, sandbox_exec, sandbox_files (list / read / write / artifacts) and sandbox_kill, plus the v2 tools sandbox_run_code, sandbox_pause, sandbox_resume, sandbox_fork and sandbox_preview (see Sandboxes v2). They call the same routes with your key, so the tool level, the limits and the metering are the same as on the REST API. sandbox_files reads return at most 256 KB inline; take bigger outputs through op: "artifacts" (signed URL + SHA-256).

BillingCopy Anchor Link

Since 17 October 2026 (00:00 UTC) exec time is charged from the wallet at €0.10 per exec-hour, with the first 10 exec-hours per user per UTC month free; usage before that date is never billed. Idle running sandboxes cost nothing. Usage is settled in 10-minute buckets (wallet_ledger source sandbox_charge). If a bucket cannot be paid, new creates and execs answer 402 insufficient_balance (with unpaid_micro_eur) until a top-up settles it.

This section prices the v1 backend. Sandboxes v2 (the default) are billed differently, see v2 billing.

Sandboxes v2Copy Anchor Link

Generally available to every key since 18 October 2026 and the default backend when backend is omitted. The REST surface above is shared: a sandbox picks its backend once, at create, and backend (v1 or v2) comes back on every sandbox object. If v2 is not available for your key and you did not ask for it explicitly, the create falls back to v1; with an explicit backend: "v2" it fails instead.

A v2 sandbox is a long-lived, isolated machine instead of a workspace restored per exec: processes keep running between calls, and the whole state (memory, running processes, /workspace) can be snapshotted, paused, resumed and forked. On v2:

• Egress works as on v1: none (default), a pypi / npm preset or an allowlist of up to 20 domains, through the codai egress proxy (plain tunnels, no credential injection). Forks inherit the parent's egress.
• Toolchain: Python 3, bash, the document libraries and Node 24 with npm in every template.
• inputs on exec and GET /artifacts (ClamAV-scanned, SHA-256, signed URLs) behave exactly as on v1.
• v1 only: POST /v1/sandboxes/{id}/snapshot answers 409 not_supported_on_v2; use pause/fork instead.

v2 limitsCopy Anchor Link

503 sandbox_capacity is transient: retry with backoff, or create with backend: "v1".

TemplatesCopy Anchor Link

When a template has a warm snapshot, the create answer carries restored: true.

Persistent kernel: run_codeCopy Anchor Link

POST /v1/sandboxes/{id}/run_code with { "code": "...", "timeout_seconds": 60 } runs a Python cell in one long-lived kernel. Globals survive between calls, across pause/resume and into forks. The answer is { stdout, stderr, result, error, duration_ms, execution_count, kernel_restarted }: result is the repr of the last expression (at most 64 KB), error is { name, value, traceback } for an uncaught exception. A cell past its timeout restarts the kernel (kernel_restarted: true, state lost). POST /v1/sandboxes/{id}/kernel/reset restarts it on purpose; files are kept.

Pause and resumeCopy Anchor Link

POST /v1/sandboxes/{id}/pause snapshots the sandbox and stops it; its status becomes paused. You can keep at most 10 paused v2 sandboxes (429 sandbox_paused_limit); delete old ones to free a place. Resuming counts against the running caps again. POST /v1/sandboxes/{id}/resume brings it back and answers the sandbox plus restored and ready_ms. restored: true means memory and processes came back exactly as they were; restored: false means a cold start from the saved workspace (files intact, kernel state lost). codai measures this inside the sandbox; it is never assumed.

ForkCopy Anchor Link

POST /v1/sandboxes/{id}/fork with { "count": 1..5, "ttl_seconds"?: n } snapshots a running sandbox (it keeps running) and starts count copies from that snapshot. Each copy is a full sandbox with its own id, workspace and kernel state, and is billed like any other. The answer is { object: "list", parent_id, data: [{ id, restored, ready_ms, error? }] }: per copy, restored: false means it started cold and error means it failed and is not running. A fork may not take a key above 6 live sandboxes, nor you above 5 running v2 sandboxes (429 sandbox_concurrency_limit).

Preview URLsCopy Anchor Link

POST /v1/sandboxes/{id}/preview with { "port": 3000, "ttl_seconds": 900 } answers { port, url, expires_at }: a signed HTTPS URL on *.sbx.codai.ro that forwards to that port inside the sandbox (a dev server, or noVNC on 6080 in desktop). Ports 1024–65535 except 8080; validity 60 s to 1 h (default 15 min). The URL needs no key: anyone holding it reaches the port until it expires, so share it only with the people who should see the app.

const sb = await client.sandboxes.create({
  template: 'codai-base',
  egress: { mode: 'preset', preset: 'pypi' },
}); // v2 by default
await client.sandboxes.runCode(sb.id, {
  code: 'import pandas as pd\ndf = pd.DataFrame({"a": [1, 2]})',
});
const r = await client.sandboxes.runCode(sb.id, { code: 'df["a"].sum()' }); // r.result === '3'
const { data } = await client.sandboxes.fork(sb.id, { count: 3 });
await client.sandboxes.pause(sb.id);
const back = await client.sandboxes.resume(sb.id); // back.restored, back.ready_ms

sb = client.sandboxes.create(backend="v2", template="desktop")
p = client.sandboxes.preview(sb["id"], 6080, ttl_seconds=600)
print(p["url"], p["expires_at"])

v2 billingCopy Anchor Link

• Running: €0.10 per wall-clock hour while the sandbox exists (busy or idle), with 5 free hours per user per UTC month (separate from the v1 exec-hours above).
• Paused: only the snapshot is stored, at €0.05 per GB-month, metered hourly.
• Charges are settled from the wallet like v1 (402 insufficient_balance when a bucket cannot be paid).

curl -X POST 'https://ai.codai.ro/v1/sandboxes' \  -H 'Content-Type: application/json' \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "object": "sandbox",  "status": "running",  "backend": "v1",  "restored": true,  "template": "string",  "egress": {    "mode": "none"  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "last_exec_at": "2019-08-24T14:15:22Z",  "metadata": {    "property1": "string",    "property2": "string"  },  "usage": {    "exec_count": 0,    "exec_seconds": 0  }}

curl -X GET 'https://ai.codai.ro/v1/sandboxes'

{  "object": "list",  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "object": "sandbox",      "status": "running",      "backend": "v1",      "restored": true,      "template": "string",      "egress": {        "mode": "none"      },      "created_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "last_exec_at": "2019-08-24T14:15:22Z",      "metadata": {        "property1": "string",        "property2": "string"      },      "usage": {        "exec_count": 0,        "exec_seconds": 0      }    }  ]}

curl -X GET 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "object": "sandbox",  "status": "running",  "backend": "v1",  "restored": true,  "template": "string",  "egress": {    "mode": "none"  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "last_exec_at": "2019-08-24T14:15:22Z",  "metadata": {    "property1": "string",    "property2": "string"  },  "usage": {    "exec_count": 0,    "exec_seconds": 0  }}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/exec' \  -H 'Content-Type: application/json' \  -d '{}'

{  "exit_code": 0,  "stdout": "string",  "stderr": "string",  "timed_out": true,  "duration_ms": 0,  "artifacts": [    {      "id": "string",      "path": "string",      "bytes": 0,      "mime": "string",      "sha256": "string",      "scan": "clean",      "url": "string",      "expires_at": "2019-08-24T14:15:22Z"    }  ],  "receipt": {    "image_digest": "string",    "template": "string",    "input_sha256": "string",    "command_sha256": "string",    "outputs": [      {        "path": "string",        "sha256": "string",        "bytes": 0      }    ],    "generation_before": 0,    "generation_after": 0  }}

curl -X PUT 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/string' \  -H 'Content-Type: application/octet-stream' \  -d 'string'

{  "path": "string",  "bytes": 0,  "sha256": "string",  "generation": 0}

curl -X GET 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/string'

"string"

curl -X GET 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/files'

{  "entries": [    {      "path": "string",      "bytes": 0,      "type": "file",      "mtime": "2019-08-24T14:15:22Z"    }  ]}

curl -X GET 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/artifacts'

{  "data": [    {      "id": "string",      "path": "string",      "bytes": 0,      "mime": "string",      "sha256": "string",      "scan": "clean",      "url": "string",      "expires_at": "2019-08-24T14:15:22Z"    }  ]}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/snapshot' \  -H 'Content-Type: application/json' \  -d '{}'

{  "object": "string",  "bytes": 0,  "sha256": "string"}

curl -X DELETE 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08'

curl -X POST 'https://ai.codai.ro/v1/sandboxes/run' \  -H 'Content-Type: application/json' \  -d '{}'

{  "exit_code": 0,  "stdout": "string",  "stderr": "string",  "timed_out": true,  "duration_ms": 0,  "artifacts": [    {      "id": "string",      "path": "string",      "bytes": 0,      "mime": "string",      "sha256": "string",      "scan": "clean",      "url": "string",      "expires_at": "2019-08-24T14:15:22Z"    }  ],  "receipt": {    "image_digest": "string",    "template": "string",    "input_sha256": "string",    "command_sha256": "string",    "outputs": [      {        "path": "string",        "sha256": "string",        "bytes": 0      }    ],    "generation_before": 0,    "generation_after": 0  }}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/run_code' \  -H 'Content-Type: application/json' \  -d '{  "code": "string"}'

{  "stdout": "string",  "stderr": "string",  "result": "string",  "error": {    "name": "string",    "value": "string",    "traceback": "string"  },  "duration_ms": 0,  "execution_count": 0,  "kernel_restarted": true}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/kernel/reset'

{  "ok": true}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/pause'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "object": "sandbox",  "status": "running",  "backend": "v1",  "restored": true,  "template": "string",  "egress": {    "mode": "none"  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "last_exec_at": "2019-08-24T14:15:22Z",  "metadata": {    "property1": "string",    "property2": "string"  },  "usage": {    "exec_count": 0,    "exec_seconds": 0  }}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/resume'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "object": "sandbox",  "status": "running",  "backend": "v1",  "template": "string",  "egress": {    "mode": "none"  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "last_exec_at": "2019-08-24T14:15:22Z",  "metadata": {    "property1": "string",    "property2": "string"  },  "usage": {    "exec_count": 0,    "exec_seconds": 0  },  "restored": true,  "ready_ms": 0}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/fork' \  -H 'Content-Type: application/json' \  -d '{  "count": 1}'

{  "object": "list",  "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "restored": true,      "ready_ms": 0,      "error": {        "code": "string",        "message": "string"      }    }  ]}

curl -X POST 'https://ai.codai.ro/v1/sandboxes/497f6eca-6276-4993-bfeb-53cbbbba6f08/preview' \  -H 'Content-Type: application/json' \  -d '{  "port": 1024}'

{  "port": 0,  "url": "http://example.com",  "expires_at": "2019-08-24T14:15:22Z"}