SDK reference

Both SDKs are thin clients for the REST API. The TypeScript SDK has no runtime dependencies and mirrors the Cloudflare Sandbox SDK surface. The Python SDK uses only the standard library and mirrors the TypeScript SDK in snake_case.

#Connecting

import { HotcellClient } from "@hotcell/sdk";
const client = new HotcellClient({ endpoint: "http://127.0.0.1:4750", apiKey: process.env.HOTCELL_API_KEY });

from hotcell import HotcellClient
client = HotcellClient(endpoint="http://127.0.0.1:4750", api_key=None)

Both resolve settings in the same order:

1. The explicit endpoint and API key arguments.
2. HOTCELL_ENDPOINT (default http://127.0.0.1:4750) and HOTCELL_API_KEY.
3. For a loopback endpoint only, the key the local daemon generated in ${HOTCELL_HOME:-~/.hotcell}/api-key.

The key is sent as Authorization: Bearer <key>.

#TypeScript

#HotcellClient

#CreateOptions

EgressPolicy fields: expiresAt, ttlMs, spendCapUsd, rateLimit: { calls?, tokens?, windowMs }, models, providers.

#Sandbox

#Session and CodeContext

#Errors

A non-2xx response throws Error("hotcell <METHOD> <path> -> <status>: <body>"). If the daemon can't be reached, the error has code: "DAEMON_UNREACHABLE".

#Example

const sandbox = await client.getSandbox(undefined, {
  repo: "https://github.com/me/app",
  setup: ["npm install"],
  egress: { spendCapUsd: 5, models: ["gpt-4o"] },
  detach: true,
  onStatus: (s, info) => console.log(s, info.statusReason),
});
const ctx = await sandbox.createCodeContext({ language: "python" });
await ctx.runCode("x = 21");
console.log((await ctx.runCode("x * 2")).results[0].text);   // "42"
await sandbox.destroy();

#Python

from hotcell import HotcellClient

client = HotcellClient()
sandbox = client.get_sandbox(repo="https://github.com/me/app", setup=["pip install -e ."], detach=True)
result = sandbox.exec("python3 -c 'print(2 + 2)'")
print(result.stdout, result.exit_code)     # "4\n" 0
sandbox.write_file("/workspace/hi.txt", "hello")
m = sandbox.metrics()
print(m.cost.total, m.usage.cpu_seconds)
sandbox.destroy()

#HotcellClient

A module-level get_sandbox(client, id=None, **options) matches the Cloudflare getSandbox shape.

#Sandbox

id, status, info, exec, exec_stream, stop, start, destroy, metrics, metrics_history, write_file, read_file, mkdir, list_files, watch, start_process, list_processes, kill_process, stream_logs, wait_for_port, expose_port, unexpose_port, list_exposed_ports, set_env_vars, get_env_vars, create_session, list_sessions, create_backup, restore_backup, list_backups, create_code_context, list_code_contexts, run_code, create_egress_token, list_egress_tokens, revoke_egress_token.

Session: session_id, exec, exec_stream, set_env_vars, destroy. CodeContext: run_code, destroy.

A non-2xx response raises HotcellError.

#Differences from the TypeScript SDK

In the current source, the Python SDK doesn't expose:

• driver, branch, networked or egress_spend_cap_usd on get_sandbox. Sandboxes use the daemon default driver.
• An egress policy object. egress is a boolean, and create_egress_token() takes no policy.
• pause() or capacity().

Use the REST API or the TypeScript SDK for those.

#Mastra

@hotcell/mastra provides HotcellSandbox, a Mastra Workspace sandbox provider. Use it where you would use E2BSandbox or ModalSandbox.

import { Agent, Workspace } from "@mastra/core";
import { HotcellSandbox } from "@hotcell/mastra";

const agent = new Agent({
  name: "coder",
  model: "openai/gpt-5",
  workspace: new Workspace({ sandbox: new HotcellSandbox({ repo: "https://github.com/me/app" }) }),
});
await agent.generate("Add a /health route and run the tests.");

HotcellSandboxOptions: endpoint, apiKey, image, egress, repo, repoRef, setup, memoryMb, cpus, pidsLimit, sandboxId.

Source: packages/sdk, sdk/python, packages/mastra.