ai-sdk-sandbox-docker weekly downloads statistics

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

Usage

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

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

• 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:

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-. 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: 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

Description from the npm listing.