@hotcell/sdk

TypeScript client for hotcell — self-hostable sandbox infrastructure for AI agents. Zero runtime dependencies; mirrors the Cloudflare Sandbox SDK surface so existing harnesses port with minimal changes, but points at your self-hosted daemon.

npm install @hotcell/sdk

import { HotcellClient } from "@hotcell/sdk";

const client = new HotcellClient({ endpoint: "http://127.0.0.1:4750" /*, apiKey */ });

const sandbox = await client.getSandbox();              // fresh sandbox
const { stdout } = await sandbox.exec("python3 -c 'print(2+2)'");

await sandbox.writeFile("/workspace/app.py", "print('hi')");
for await (const ev of sandbox.execStream("python3 /workspace/app.py")) {
  if (ev.type === "stdout") process.stdout.write(ev.data);
}

await sandbox.destroy();

Highlights

• exec / execStream, writeFile/readFile/mkdir/listFiles, watch
• background processes (startProcess/listProcesses/killProcess/streamLogs/waitForPort)
• preview URLs (exposePort), persistent Sessions, stateful CodeContexts
• backups, lifecycle (stop/start, idle auto-pause), metrics/metricsHistory
• egress credential proxy: createEgressToken/listEgressTokens/revokeEgressToken, or create with { egress: true }

Configure the endpoint via the constructor or HOTCELL_ENDPOINT, and the API key via apiKey or HOTCELL_API_KEY.

See the main README for the daemon, CLI, dashboard, and full docs.

License

Apache-2.0