forkd TypeScript SDK — spawn, branch, and exec microVMs

npm install @deeplethe/forkd
# or
pnpm add @deeplethe/forkd

import { Controller } from '@deeplethe/forkd';

const ctrl = new Controller({
  baseUrl: 'http://127.0.0.1:8889',  // or env FORKD_URL
  token: process.env.FORKD_TOKEN,    // or env FORKD_TOKEN
  timeoutMs: 60_000,
});

listSnapshots(): Promise<SnapshotInfo[]>

deleteSnapshot(tag: string): Promise<void>

spawnSandboxes(options: {
  snapshotTag: string;
  n?: number;
  perChildNetns?: boolean;
  memoryLimitMib?: number;
  prewarm?: boolean;
  liveFork?: boolean;
  hugepages?: boolean;
}): Promise<SandboxInfo[]>

listSandboxes(): Promise<SandboxInfo[]>

getSandbox(id: string): Promise<SandboxInfo>

killSandbox(id: string): Promise<void>

branchSandbox(sandboxId: string, options?: BranchOptions): Promise<SnapshotInfo>

execCommand(
  sandboxId: string,
  args: string[],
  options?: { timeoutSecs?: number },
): Promise<ExecResult>

evalCode(sandboxId: string, code: string): Promise<EvalResult>

pingSandbox(sandboxId: string): Promise<PingResult>

static async create(options: {
  snapshotTag: string;
  perChildNetns?: boolean;
  memoryLimitMib?: number;
  prewarm?: boolean;
} & ControllerOptions): Promise<Sandbox>

const sb = await Sandbox.create({
  snapshotTag: 'python-3-12-slim',
  prewarm: true,
  token: process.env.FORKD_TOKEN,
});
try {
  const r = await sb.exec(['python3', '-c', 'print(2+2)']);
  console.log(r.stdout); // "4\n"
} finally {
  await sb.kill();
}

static async with<T>(
  options: Parameters<typeof Sandbox.create>[0],
  fn: (sb: Sandbox) => Promise<T>,
): Promise<T>

const result = await Sandbox.with(
  { snapshotTag: 'python-3-12-slim' },
  async (sb) => sb.exec(['python3', '-c', 'print(2+2)']),
);
console.log(result.stdout); // "4\n"

new Sandbox(controller: Controller, info: SandboxInfo)

const [info] = await ctrl.spawnSandboxes({ snapshotTag: 'pyagent', n: 1 });
const sb = new Sandbox(ctrl, info);

exec(args: string[], options?: { timeoutSecs?: number }): Promise<ExecResult>

eval(code: string): Promise<unknown>

ping(): Promise<Record<string, unknown>>

branch(options?: {
  tag?: string;
  diff?: boolean;
  measure_diff?: boolean;
}): Promise<SnapshotInfo>

kill(): Promise<void>

interface SandboxInfo {
  id: string;
  snapshot_tag: string;
  netns: string | null;
  guest_addr: string;
  created_at_unix: number;
  pid: number | null;
  memory_limit_mib: number | null;
  /** v0.3+: any BRANCH has been taken from this sandbox. */
  has_branched?: boolean;
  /** v0.3.1+: chain head for the next diff BRANCH. */
  last_branch_memory_path?: string | null;
}

interface SnapshotInfo {
  tag: string;
  dir: string;
  created_at_unix: number;
  /** Set when produced by BRANCH; the source sandbox id. */
  branched_from?: string;
  /** v0.2.5+: source-VM pause window in ms during BRANCH. */
  pause_ms?: number;
  /** v0.3+: time spent in the Diff snapshot call (subset of pause_ms). */
  diff_ms?: number;
  /** v0.3+: on-disk bytes of the diff = dirty page count. */
  diff_physical_bytes?: number;
  /** v0.3+: full guest-RAM size (what a Full snapshot would have written). */
  diff_logical_bytes?: number;
  /**
   * v0.4+: live BRANCH lifecycle marker.
   * "writing" while the background memory copy is in flight (wait: false),
   * "ready" once the snapshot is consumable,
   * "failed" if the background copy hit an error.
   */
  status?: "writing" | "ready" | "failed";
}

type BranchMode = "full" | "diff" | "live";

interface SpawnOptions {
  snapshot_tag: string;
  n?: number;
  per_child_netns?: boolean;
  memory_limit_mib?: number;
  prewarm?: boolean;
  live_fork?: boolean;
  hugepages?: boolean;
}

interface BranchOptions {
  tag?: string;
  mode?: BranchMode;
  /** Legacy: equivalent to mode: "diff". Kept for v0.3.x daemon compat. */
  diff?: boolean;
  measure_diff?: boolean;
  /** v0.4+: default true. Set false for fire-and-forget live BRANCH. */
  wait?: boolean;
}

interface ExecResult {
  stdout: string;
  stderr: string;
  exit_code: number;
}

interface EvalResult {
  result: unknown;
  error: string | null;
  exit_code: number;
}

interface PingResult {
  [key: string]: unknown;
}

class ControllerError extends Error {
  readonly status: number;   // HTTP status code
  readonly body: unknown;    // Parsed JSON or raw string
  readonly url: string;      // Full URL of the failed request
}

import { ControllerError } from '@deeplethe/forkd';

try {
  await ctrl.getSandbox('sb-missing');
} catch (e) {
  if (e instanceof ControllerError && e.status === 404) {
    console.log('sandbox not found');
  } else {
    throw e;
  }
}

import { Controller, Sandbox, ControllerError } from '@deeplethe/forkd';

const ctrl = new Controller({ token: process.env.FORKD_TOKEN });

// ── Quick path: spawn + use + auto-cleanup ────────────────────────────
const echoResult = await Sandbox.with(
  { snapshotTag: 'python-3-12-slim', token: process.env.FORKD_TOKEN },
  async (sb) => sb.exec(['python3', '-c', 'import numpy; print(numpy.zeros(3))']),
);
console.log(echoResult.stdout); // "[0. 0. 0.]\n"

// ── Long-lived path: BRANCH + fan-out ────────────────────────────────
// Spawn a parent with memfd-backed RAM (prerequisite for mode: "live").
const [parent] = await ctrl.spawnSandboxes({
  snapshotTag: 'pyagent',
  n: 1,
  perChildNetns: true,
  liveFork: true,
});
console.log(`spawned ${parent.id} at ${parent.guest_addr}`);

// Drive the parent via exec.
const warmup = await ctrl.execCommand(parent.id, [
  'python3', '-c', 'import numpy, torch; print("warmed")'
]);
console.log(warmup.stdout.trim()); // "warmed"

// BRANCH live: source pause drops to sub-50 ms.
// wait: false returns after the source resumes (~10 ms).
const branch = await ctrl.branchSandbox(parent.id, {
  tag: 'checkpoint-1',
  mode: 'live',
  wait: false,
});
console.log(`branch ${branch.tag} status=${branch.status}`); // "writing"

// Poll until the background copy completes.
let ready = false;
while (!ready) {
  await new Promise((r) => setTimeout(r, 200));
  const snapshots = await ctrl.listSnapshots();
  const snap = snapshots.find((s) => s.tag === branch.tag);
  if (snap?.status === 'ready') ready = true;
  if (snap?.status === 'failed') throw new Error('live branch failed');
}

// Fan out 5 grandchildren from the checkpoint.
const kids = await ctrl.spawnSandboxes({ snapshotTag: branch.tag, n: 5 });
console.log(`spawned ${kids.length} grandchildren`);

// Cleanup
await ctrl.killSandbox(parent.id);
await Promise.all(kids.map((k) => ctrl.killSandbox(k.id)));