TypeScript SDK

npm install @opencomputer/sdk

import { Sandbox, Usage, Tags } from "@opencomputer/sdk";
import { Image } from "@opencomputer/sdk/dist/image.js";
import { Snapshots } from "@opencomputer/sdk/dist/snapshot.js";

const sandbox = await Sandbox.create({ template: "my-stack", timeout: 600 });

const sandbox = await Sandbox.connect("sb-abc123");

const forked = await Sandbox.createFromCheckpoint("cp-abc123");

const result = await Sandbox.createCheckpointPatch("cp-abc", { script: "apt install -y curl" });

const patches = await Sandbox.listCheckpointPatches("cp-abc");

await Sandbox.deleteCheckpointPatch("cp-abc", "pa-xyz");

interface SandboxOpts {
  template?: string;
  timeout?: number;
  apiKey?: string;
  apiUrl?: string;
  envs?: Record<string, string>;
  metadata?: Record<string, string>;
  cpuCount?: number;
  memoryMB?: number;
  image?: Image;
  snapshot?: string;
  onBuildLog?: (log: string) => void;
}

interface CheckpointInfo {
  id: string;
  sandboxId: string;
  orgId: string;
  name: string;
  sandboxConfig: object;
  status: string;       // "processing" | "ready" | "failed"
  sizeBytes: number;
  createdAt: string;
}

interface PatchInfo {
  id: string;
  checkpointId: string;
  sequence: number;
  script: string;
  description: string;
  strategy: string;     // "on_wake"
  createdAt: string;
}

interface PatchResult {
  patch: PatchInfo;
}

interface PreviewURLResult {
  id: string;
  sandboxId: string;
  orgId: string;
  hostname: string;
  customHostname?: string;
  port: number;
  cfHostnameId?: string;
  sslStatus: string;
  authConfig?: object;
  createdAt: string;
}

const usage = new Usage("https://app.opencomputer.dev", process.env.OPENCOMPUTER_API_KEY!);
const tags = new Tags("https://app.opencomputer.dev", process.env.OPENCOMPUTER_API_KEY!);

const r = await usage.forSandbox("sb-abc123", {
  from: "2026-05-27T00:00:00Z",
  to: "2026-05-27T01:00:00Z",
});

console.log(r.totals.memoryAllocatedGbSeconds, r.totals.memoryUsedGbSeconds);

const page = await usage.bySandbox({
  filter: { "tag:team": "payments" },
  limit: 20,
});

const byTeam = await usage.byTag("team", {
  filter: { "tag:env": "prod" },
});

await tags.set("sb-abc123", {
  team: "payments",
  env: "prod",
});

const current = await tags.get("sb-abc123");

const keys = await tags.listKeys();

const session = await sandbox.agent.start({
  prompt: "Build a todo app",
  onEvent: (e) => console.log(e.type),
});

interface AgentEvent {
  type: string;
  [key: string]: unknown;
}

interface McpServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

const result = await sandbox.exec.run("npm test", { cwd: "/app" });

const session = await sandbox.exec.start("node server.js", {
  onStdout: (data) => process.stdout.write(data),
});

const sh = await sandbox.exec.shell({ cwd: "/app" });
await sh.run("export NODE_ENV=test");
const r = await sh.run("npm test");
await sh.close();

interface ProcessResult {
  exitCode: number;
  stdout: string;
  stderr: string;
}

interface ExecSessionInfo {
  sessionID: string;
  sandboxID: string;
  command: string;
  args: string[];
  running: boolean;
  exitCode?: number;
  startedAt: string;
  attachedClients: number;
}

interface EntryInfo {
  name: string;
  isDir: boolean;
  path: string;
  size: number;
}

import { Image } from "@opencomputer/sdk";

const image = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests', 'pandas'])
  .env({ PROJECT_ROOT: '/workspace' })
  .workdir('/workspace');

import { Snapshots } from "@opencomputer/sdk";

const snapshots = new Snapshots();
// or with explicit config:
const snapshots = new Snapshots({ apiKey: "...", apiUrl: "..." });

interface SnapshotInfo {
  id: string;
  name: string;
  status: string;       // "building" | "ready" | "failed"
  contentHash: string;
  checkpointId: string;
  manifest: object;
  createdAt: string;
  lastUsedAt: string;
}

import { SecretStore } from '@opencomputer/sdk';

const store = await SecretStore.create({
  name: 'my-agent-secrets',
  egressAllowlist: ['api.anthropic.com'],
});

const stores = await SecretStore.list();

const store = await SecretStore.get('store-uuid');

const updated = await SecretStore.update('store-uuid', {
  name: 'new-name',
  egressAllowlist: ['api.anthropic.com', '*.openai.com'],
});

await SecretStore.delete('store-uuid');

await SecretStore.setSecret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...');

await SecretStore.setSecret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...', {
  allowedHosts: ['api.anthropic.com'],
});

const entries = await SecretStore.listSecrets('store-uuid');
// [{ name: 'ANTHROPIC_API_KEY', allowedHosts: ['api.anthropic.com'], ... }, ...]

await SecretStore.deleteSecret('store-uuid', 'DATABASE_URL');

import { Sandbox } from '@opencomputer/sdk';

const sandbox = await Sandbox.create({
  secretStore: 'my-agent-secrets',
  timeout: 600,
});

// Secrets are available as sealed env vars
const result = await sandbox.commands.run('echo $ANTHROPIC_API_KEY');
// stdout: "osb_sealed_abc123..." (sealed, not the real key)

// But outbound HTTPS requests get the real value substituted by the proxy
const apiResult = await sandbox.commands.run(
  'curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" ...'
);
// The proxy replaces the sealed token with the real key before it hits Anthropic

import { startSessionOnDocument, sessionIdempotencyKey } from "@opencomputer/sdk";

const { document, session } = await startSessionOnDocument({
  apiKey: process.env.OPENCOMPUTER_API_KEY!,
  projectId: "<project-id>",
  environment: "development",
  agent: "<agent-id>",
  resource: "notes",
  documentId: "workshop",
  document: { title: "Workshop notes" },
  idempotencyKey: "topic/workshop/1",
});