AI SDK - Docker Sandbox

This package is experimental.

A HarnessV1SandboxProvider backed by a Docker container. Each session runs its file I/O, run, and spawn through docker exec, so the container is the trust boundary.

Requirements

A running Docker daemon and the docker CLI on the host.

Install

npm i ai-sdk-sandbox-docker @ai-sdk/harness

Usage

The factory is synchronous. createSession() creates the container and publishes its ports to 127.0.0.1.

import { createDockerSandbox } from 'ai-sdk-sandbox-docker';

const dockerSandbox = createDockerSandbox({
  image: 'node:22',
  ports: [3000],
});

const networkSession = await dockerSandbox.createSession();
const session = networkSession.restricted();

await session.writeTextFile({ path: 'hello.txt', content: 'hi' });

const { stdout } = await session.run({ command: 'cat hello.txt' });
console.log(stdout); // "hi"

await networkSession.stop(); // removes the created container

networkSession.restricted() is typed as Experimental_SandboxSession, the reduced surface (file I/O, run, spawn) safe to pass to AI SDK tools via experimental_sandbox. The network session keeps the infra surface (ports, getPortUrl, setPorts, setNetworkPolicy, stop) that only the harness reaches for.

Configuration

const dockerSandbox = createDockerSandbox({
  image: 'node:22',
  workdir: '/workspace',
  ports: [3000],
  createArgs: ['-v', `${process.cwd()}:/workspace`],
  keep: false,
});

• image Image for a created container. Ignored when container is set. Defaults to node:22.
• container Attach to an existing container by name or id. The caller owns its lifecycle and port publishing; the provider never creates or removes it.
• workdir Working directory inside the container. Defaults to /workspace. Relative paths in file operations resolve against it.
• docker Path to the docker binary. Defaults to docker.
• createArgs Extra arguments passed to docker run. Use it for volume mounts (-v), container env (-e), and networking (--network).
• ports Ports to publish from container to host. The first port serves as the bridge; when omitted the provider leases one.
• keep Keep a created container after the session stops. Defaults to false.

Mount a host directory to run the agent against a real repository:

createDockerSandbox({
  image: 'node:22',
  workdir: '/repo',
  createArgs: ['-v', `${process.cwd()}:/repo`],
});

Authentication

The provider uses the host's Docker configuration. To pull a private image, run docker login first. To target a remote daemon, set DOCKER_HOST or select a Docker context; the provider shells out to the same docker CLI and inherits that configuration.

Lifecycle

A created container is named ai-sdk-sandbox-<sessionId>. resumeSession({ sessionId }) rebinds to it by name without checking that it is still running; if the container is gone the first exec fails rather than the resume. stop() removes a container the provider created, unless keep is set. For an attached container (container set), stop() leaves it running.

Ports and network policy

Ports are published container to host 1:1 at creation, so getPortUrl resolves to http://127.0.0.1:<port> and throws HarnessCapabilityUnsupportedError for a port that was not published. Docker cannot publish new ports to a running container, so a port requested after creation must already be in ports, and resumeSession and attach mode expose only the ports declared in ports. setNetworkPolicy is a no-op; fix the container network at boot with createArgs (for example --network).

Cancellation

spawn records the in-container PID and terminates it on kill() or stop(). Use those to cancel a spawned process. docker exec does not forward signals, so aborting through abortSignal only kills the local docker exec client: an aborted run, or an aborted spawn whose kill() you never call, leaves its command running in the container until the container stops.

License

Apache-2.0