deepagents-sbx (JavaScript)

Docker Sandboxes (sbx) microVM sandbox backend for Deep Agents.

Implements the deepagents JavaScript BaseSandbox (SandboxBackendProtocolV2) on top of a Docker Sandboxes microVM — its own kernel plus a private Docker daemon.

Install

npm install deepagents-sbx deepagents

Requires Node 20+ and the free sbx CLI, installed and signed in (sbx login; sbx policy init balanced once).

Use

import { createDeepAgent } from "deepagents";
import { SbxSandbox } from "deepagents-sbx";

const backend = new SbxSandbox({ memory: "4g" }); // created lazily on first use
try {
  const agent = createDeepAgent({ model, backend });
  await agent.invoke({ messages: [{ role: "user", content: "Run the test suite" }] });
} finally {
  await backend.close(); // removes the microVM when autoRemove is set (default)
}

Bind-mount a host project (mounted at the same absolute path inside the VM):

const backend = new SbxSandbox({ workspace: "/path/to/project" });

Attach to an existing sandbox without creating one:

const backend = await SbxSandbox.attach("my-sandbox");

Options

| Option | Default | Meaning | |---|---|---| | name | deepagents-sbx-<random> | Sandbox handle. | | agent | "shell" | Built-in sbx agent image. | | workspace | — | Host dir bind-mounted at the same absolute path. | | cpus / memory / profile | sbx defaults | sbx create sizing/governance. | | transport | CliSbxTransport | Swap the transport implementation (ApiSbxTransport for the cloud API). | | timeout | 120 | Per-command timeout (seconds). | | maxOutputBytes | 524288 | Output cap; the child is killed at the cap. | | maxDownloadBytes | 52428800 | Cap on a single downloaded file (50 MiB); larger files fail with file_too_large. 0 disables. | | autoRemove | true | Delete on close(). | | autoCreate | true | Create on first use if missing. | | pull | sbx default | Image pull policy, e.g. "missing". |

Unlike the Python port, the JS backend is pure POSIX and needs no python3 inside the sandbox.

Cloud

const backend = new SbxSandbox({ cloud: true, cpus: 1, memory: "2g", ttl: "10m" });

Cloud sandboxes are billable, have no host workspace, and must use a billable shape (micro/small/medium/large/xl); an invalid pair throws SbxShapeError before any call. Use backend.ttl() / backend.extendTtl("5m") and always set ttl so an abandoned sandbox stops billing.

For direct API access with no sbx process, opt into the API transport built on the experimental @docker/sandboxes SDK (an optional peer dependency — npm install @docker/sandboxes):

import { pat } from "@docker/sandboxes";
import { ApiSbxTransport, SbxSandbox } from "deepagents-sbx";

const transport = new ApiSbxTransport({
  sdkOptions: { auth: pat({ username: process.env.DOCKER_ID!, personalAccessToken: process.env.DOCKER_PAT! }) },
});
const backend = new SbxSandbox({ cloud: true, ttl: "10m", transport });

Auth is independent of sbx login.

Testing

npm test                # unit + contract (fake sbx, no Docker)
npm run test:integration  # real microVMs (needs sbx login + virtualization)

License

MIT