Docs / SDKs
TYPESCRIPT & PYTHON SDKS

Zero-dependency SDKs
built for production agent loops.

Install @uncage/sdk (TypeScript/ESM) or uncage-py (sync + asyncio Python). Both ship with zero third-party runtime dependencies and full ergonomic handles for exec(), fork(), pause(), and resume().

TYPESCRIPT / JAVASCRIPT (NODE 18+ · BUN · DENO)

@uncage/sdk

npm install @uncage/sdk
agent-loop.ts — Pause during LLM waits & fork() parallel patch tests ZERO DEPS
import { UncageClient } from "@uncage/sdk";

const uncage = new UncageClient({
  baseUrl: process.env.UNCAGE_API_URL ?? "https://api.uncage.sh",
  apiKey: process.env.UNCAGE_API_KEY,
});

async function runCodingAgent(projectId: string, repoUrl: string) {
  // 1. Provision a 2 vCPU · 4 GB sandbox in us-east
  const box = await uncage.sandboxes.create({
    projectId,
    name: "swe-agent-session",
    region: "us-east",
    vcpu: 2,
    memoryMb: 4096,
    idleTimeoutSeconds: 180,
  });

  // 2. Clone repo and install dependencies once
  await box.exec(["git", "clone", repoUrl, "/work"], 60);
  await box.exec(["sh", "-c", "cd /work && npm ci"], 120);

  // 3. Pause immediately while calling your LLM API ($0.00/hr compute!)
  await box.pause();
  const [patchA, patchB] = await generateCandidatePatchesWithLLM();

  // 4. Resume and fork in ~180ms to verify both patches in parallel
  await box.resume();
  const [branchA, branchB] = await Promise.all([
    box.fork("swe-agent-patch-a"),
    box.fork("swe-agent-patch-b"),
  ]);

  const [resA, resB] = await Promise.all([
    branchA.exec(["sh", "-c", `cd /work && echo "${patchA}" | git apply && npm test`], 90),
    branchB.exec(["sh", "-c", `cd /work && echo "${patchB}" | git apply && npm test`], 90),
  ]);

  console.log({ patchAExit: resA.exit_code, patchBExit: resB.exit_code });

  // Clean up ephemeral forks; pause parent for the next user turn
  await Promise.all([branchA.delete(), branchB.delete(), box.pause()]);
}
deploy-stack.ts — Provision PostgreSQL 17 + deploy HTTPS app on private DNS APPS + DB
import { UncageClient } from "@uncage/sdk";

const uncage = new UncageClient({
  baseUrl: "https://api.uncage.sh",
  apiKey: process.env.UNCAGE_API_KEY,
});

// Provision dedicated NVMe PostgreSQL 17
const db = await uncage.databases.create({
  projectId: "proj_prod",
  name: "pg-main",
  engine: "postgres",
  region: "eu-central",
  vcpu: 2,
  memoryMb: 4096,
  diskGb: 20,
});

// Deploy an HTTPS web app talking to Postgres over private internal DNS
const app = await uncage.apps.deploy({
  projectId: "proj_prod",
  name: "checkout-api",
  image: "ghcr.io/acme/checkout-api:v1.8",
  region: "eu-central",
  exposePort: 8080,
  idleTimeoutSeconds: 300,
  env: {
    DATABASE_URL: `postgres://postgres:secret@${db.internal_dns}:5432/postgres`,
  },
});

console.log("Live HTTPS endpoint:", `https://${app.public_host}`);
PYTHON 3.10+ (SYNC + ASYNCIO)

uncage-py

pip install uncage-py
eval_sync.py — Context-manager auto-pause & live fork() STDLIB ONLY
import os
from uncage import UncageClient

client = UncageClient(
    base_url=os.getenv("UNCAGE_API_URL", "https://api.uncage.sh"),
    api_key=os.environ["UNCAGE_API_KEY"],
)

# Context manager automatically pauses the sandbox to $0/hr on exit
with client.create_sandbox(
    project_id="proj_agents",
    name="py-eval-agent",
    region="us-east",
    vcpu=2,
    memory_mb=4096,
    idle_timeout_seconds=120,
) as box:
    setup = box.exec(["python3", "-m", "pip", "install", "-q", "pytest"])
    assert setup.exit_code == 0

    # Fork live memory + disk state for an isolated experiment (~180ms)
    alt = box.fork(name="py-eval-agent-alt")
    try:
        result = alt.exec(["pytest", "-q", "tests/"], timeout_sec=60)
        print("stdout:", result.stdout)
        print("exit_code:", result.exit_code)
    finally:
        alt.delete()
# box.pause() runs automatically here -> $0.00/hr while idle
rollout_async.py — Parallel AsyncUncageClient RL / SWE-bench rollouts ASYNCIO
import asyncio
import os
from uncage import AsyncUncageClient

async def evaluate_candidates(project_id: str, scripts: list[str]) -> list[int]:
    client = AsyncUncageClient(
        base_url="https://api.uncage.sh",
        api_key=os.environ["UNCAGE_API_KEY"],
    )

    # Warm one base microVM once
    base = await client.create_sandbox(
        project_id=project_id,
        name="rl-rollout-base",
        region="us-east",
        vcpu=2,
        memory_mb=2048,
    )

    async def run_one(idx: int, script: str) -> int:
        forked = await base.fork(name=f"rl-rollout-{idx}")
        try:
            res = await forked.exec(["python3", "-c", script], timeout_sec=30)
            return res.exit_code or 0
        finally:
            await forked.delete()

    try:
        return await asyncio.gather(*(run_one(i, s) for i, s in enumerate(scripts)))
    finally:
        await base.pause()  # Keep warm snapshot at $0/hr for next batch
API PARITY

Core methods across TypeScript and Python.

Operation TypeScript (@uncage/sdk) Python (uncage-py)
Create Sandbox / Desktop uncage.sandboxes.create(opts) client.create_sandbox(project_id, name, ...)
Run Command box.exec(cmd, timeoutSec) box.exec(cmd, timeout_sec=30)
Live Memory + Disk Fork box.fork(newName) box.fork(name="...")
Pause to $0/hr box.pause() box.pause()
Sub-Second Resume box.resume() box.resume()
Provision Database uncage.databases.create(opts) client.create_database(project_id, name, engine="postgres")
Deploy HTTPS App uncage.apps.deploy(opts) client.deploy_app(project_id, name, image)
SDK FAQ

Common SDK integration questions.

01 Do the TypeScript and Python SDKs require heavy third-party dependencies?
No. @uncage/sdk uses native Web Fetch (Node 18+, Bun, Deno, Edge runtimes) with zero runtime dependencies, and uncage-py uses the Python standard library (urllib + asyncio) with zero external packages required.
02 Does uncage-py support both synchronous and async/await agent loops?
Yes. Import UncageClient for synchronous scripts (including context-manager auto-pause via with client.create_sandbox(...) as box:) or AsyncUncageClient for concurrent asyncio agent fleets.
03 Can I pass a custom timeout to exec() for long builds or test suites?
Yes. Both box.exec(cmd, timeoutSec) in TypeScript and box.exec(cmd, timeout_sec=...) in Python accept per-command timeouts so runaway LLM scripts never hang your orchestrator.
WANT ZERO GLUE CODE FOR CLAUDE OR CURSOR?

Connect our native MCP server in 30 seconds.

Expose all 9 sandbox, database, and app deployment tools directly to Claude Desktop, Cursor, or custom MCP agents.

✓ $10 starter credit on signup
✓ Strictly $0.00/hr compute when sleeping
✓ Sub-second boot across 4 global regions