@torkbot/sandbox-code-mode

Run code-mode programs inside lifecycle-managed Sandbox microVMs.

This package owns one narrow boundary: boot a caller-defined Sandbox VM, pair it with SandboxNodeRuntime, and close the VM with the returned session. Sandbox remains the authority for persistence, resources, mounts, and network access. The embedding application remains the authority for machine identity, warm-session caching, and how runtime facts are presented to an agent.

Status

This repository is pre-release. It currently uses sibling checkouts of torkbot/sandbox and torkbot/code-mode because the required Sandbox process pipe API and @torkbot/code-mode package have not both been published to npm. The package is private to prevent an accidental release with local dependency references.

Usage

import { createClient } from "@torkbot/code-mode";
import { defineSandbox, rootfs } from "@torkbot/sandbox";
import { image as alpine323Agent } from
  "@torkbot/sandbox-image-alpine-3.23-agent";
import { openSandboxCodeMode } from "@torkbot/sandbox-code-mode";

const definition = defineSandbox({
  rootfs: rootfs.persistent({
    base: alpine323Agent,
    path: machineStatePath,
  }),
  resources: {
    cpus: 2,
    memoryMiB: 2048,
  },
});

await using session = await openSandboxCodeMode({
  definition,
  boot: {
    cwd: "/workspace",
  },
  nodePath: "/usr/bin/node",
});

const client = createClient({
  toolbox,
  runtime: session.runtime,
});

The absolute persistent-overlay path is deliberately supplied by the embedder. TorkBot can derive it from a durable lane or actor identity; a coding-agent plugin can derive it from its project identity. Reopening the definition with the same path restores that machine's filesystem state.

For ephemeral machines, remote block storage, custom mounts, or network access, construct a different SandboxDefinition and pass it through the same API. Callers that already own a booted VM can use @torkbot/code-mode/sandbox-node directly.

Development

The sibling repositories must exist at:

../sandbox
../code-mode
../sandbox-code-mode

Then run:

npm install
npm run typecheck
npm test
npm run build