@agentforge-ai/sandbox

@agentforge-ai/sandbox

Docker-based sandbox provider for AgentForge agent tool execution isolation.

Overview

This package implements container-based isolation for agent tool execution using Docker. It provides:

• 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

Docker Connection

Connects to the Docker daemon via:

• Unix socket (default): /var/run/docker.sock
• TCP: configure via SandboxManager({ dockerHost: { host, port, protocol } })
• Env: DOCKER_HOST environment variable

Requirements

• Node.js ≥ 18
• Docker Engine installed and running on the host
• dockerode peer dependency

License

Apache-2.0