Sandbox API

Base origin: https://api.tachyonic.sh. Management routes below use /v1. The platform API also serves its existing /api/v1 routes.

Authentication

Send a workspace-bound key in x-api-key. Create keys in Settings > API Keys, with only the scopes the caller needs:

• sandbox:read for list, detail, events, usage, and file reads.
• sandbox:write for create, exec, shell, file writes, resume, and delete.
• usage:read for organization usage and workspace budget reads.
• budget:write to change the workspace budget.

The service resolves the workspace from the key. A caller cannot select another workspace by sending identity headers. A revoked key fails its next request. See Authentication for device login and key handling.

This Python example reads the key in-process from an existing secret environment. It does not put the key in command arguments or a URL:

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.tachyonic.sh/v1/whoami",
    headers={"x-api-key": os.environ["TACHYONIC_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    identity = json.load(response)
print({name: identity[name] for name in ("org_id", "workspace_id", "scopes")})

Sandbox routes

Create

The create body accepts image, region, provider, isolation, cpu, memory_mib, disk_gib, timeout in seconds, budget_usd, egress, env, name, metadata, wait, and on_interruption where supported. Check pool capabilities before requesting interruption behavior.

{
  "image": "tachyonic.sh/base",
  "isolation": "container",
  "cpu": 1,
  "memory_mib": 1024,
  "timeout": 1800,
  "egress": {"policy": "allowlist", "allow": ["api.example.com"]}
}

Creation can require capacity to start. Use the returned record and readiness state before issuing commands. Container isolation shares the host kernel; an explicit isolation requirement is refused if matching capacity is unavailable.

Account routes

Budget updates use monthly_usd and an action of stop or alert. Device-login keys cannot change budgets.

Errors

Sandbox errors carry a machine-readable code and message. Authentication errors can be refused before the sandbox handler is reached.

Use the CLI for the corresponding command and exit-code contract.