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