DockerSandbox — a container-backed SandboxProvider that manages the full lifecycle of a Docker container
ContainerPool — a warm-container pool to amortise Docker cold-start latency (LRU eviction, idle timeout)
SandboxManager — factory that creates the right sandbox type (Docker vs E2B) based on config, with graceful shutdown on process exit

Installation

pnpm add @agentforge-ai/sandbox dockerode

Quick Start

import { SandboxManager } from '@agentforge-ai/sandbox';

const manager = new SandboxManager({ provider: 'docker' });
await manager.initialize();

const sb = await manager.create({ scope: 'agent', workspaceAccess: 'none' });

const { stdout, exitCode } = await sb.exec('node --version');
console.log(stdout); // v22.x.x

await sb.writeFile('/tmp/hello.js', 'console.log("hello from container")');
const result = await sb.exec('node /tmp/hello.js');
console.log(result.stdout); // hello from container

await manager.destroy(sb);
await manager.shutdown();

Configuration

`DockerSandboxConfig`

Field	Type	Default	Description
`scope`	`'session' \| 'agent' \| 'shared'`	required	Lifecycle scope
`workspaceAccess`	`'none' \| 'ro' \| 'rw'`	required	Host workspace mount mode
`image`	`string`	`'node:22-slim'`	Docker image
`workspacePath`	`string`	—	Host workspace directory
`containerWorkspacePath`	`string`	`'/workspace'`	Mount point inside container
`resourceLimits.cpuShares`	`number`	Docker default	CPU weight
`resourceLimits.memoryMb`	`number`	unlimited	Memory cap in MB
`resourceLimits.pidsLimit`	`number`	`256`	Max PIDs in container
`resourceLimits.networkDisabled`	`boolean`	`false`	Disable networking
`binds`	`string[]`	`[]`	Extra bind mounts (`host:container:mode`)
`env`	`Record<string, string>`	`{}`	Environment variables
`timeout`	`number`	none	Auto-kill after N seconds

`PoolConfig`

const pool = new ContainerPool({
  image: 'node:22-slim',
  scope: 'agent',
  maxSize: 3,             // warm containers to keep ready (default: 3)
  idleTimeoutSeconds: 300 // evict after 5 min idle (default: 300)
});

await pool.warmUp();
const sb = await pool.acquire();
// ... use sandbox ...
await pool.release(sb);
await pool.drain(); // cleanup

Environment Variables

Variable	Description
`DOCKER_HOST`	Docker daemon host (default: Unix socket)
`DOCKER_IMAGE`	Default image for agent sandboxes
`AGENTFORGE_ALLOWED_IMAGES`	Comma-separated image prefixes allowed in production

Security

Blocked bind mounts: /var/run/docker.sock, /etc, /proc, /sys, /dev, /boot, /root
Capabilities: All Linux capabilities dropped by default (CapDrop: ALL)
No new privileges: SecurityOpt: no-new-privileges:true applied to every container
PID limit: Default 256 PIDs per container to prevent fork bombs
Image validation: In production (NODE_ENV=production), only images with approved prefixes are allowed
Command validation: Defense-in-depth checks block docker.sock access and nsenter attempts