@agentskit/sandbox — for agents

#Install

npm install @agentskit/sandbox
# optional peer for the default E2B cloud backend:
npm install @e2b/code-interpreter

#Primary exports

• createSandbox(config?) — facade over a SandboxBackend or E2B (apiKey required when no backend). Defaults: network: false, timeout: 30_000, language javascript.
• sandboxTool(config?) — ready-made code_execution tool (js / python).
• createE2BBackend({ apiKey, timeout?, network? }) — E2B VM backend; maps to Sandbox.create({ apiKey, timeoutMs, allowInternetAccess }).
• Types: Sandbox, SandboxConfig, SandboxBackend, ExecuteOptions, ExecuteResult.

#Policy wrapper

• createMandatorySandbox({ sandbox, policy }) — enforce allow / deny / requireSandbox / validators across every tool.
• requireSandbox does not execute the original tool body. It delegates args to sandbox.execute (routing shim).

#Browser (@agentskit/sandbox/web)

• webWorkerBackend(opts?) / runStreaming(code, onChunk, opts?) — JavaScript only.
• Isolation: thread + DOM only. Not a network/filesystem security boundary. Not WebContainer.

#Local-process runtimes

Host-process isolation complementing the cloud E2B backend. Each implements the SandboxRuntime adapter (spawn / optional exec) via an injected Spawner (no native deps).

• noneSandbox — in-process, no isolation (spawn rejects).
• processSandbox(opts?) — child-process with env allowlisting (exposeAllowedEnvKeys).
• sandboxExecRuntime({ policy }) — macOS seatbelt; profile scopes file-read to system paths + workspaceRoot + extraReadablePaths (no global file-read*).
• bwrapRuntime({ policy }) — Linux bubblewrap; level remains 'process' for registry compatibility (beta; not remapped to 'container' yet).
• dockerRuntime({ policy }) — docker run --rm with cap-drop / no-new-privileges / read-only rootfs; rejects obvious escape extraArgs / capabilities.
• nodeSpawner() — default Spawner; combined stdout+stderr byte cap + timeout.
• SandboxRegistry / SANDBOX_LEVELS / assertStrongIsolation — runtime discovery and isolation policy.
• Profile and capability helpers: renderSandboxExecProfile, renderBwrapArgs, isBwrapSupported, getBwrapPath, renderDockerArgs.
• Isolation classification helpers: isStrongIsolation, isWeakIsolation, weakSandboxBanner, WeakSandboxError.

#Config notes

• memoryLimit: type-compatible hint for custom backends. Not applied by E2B or Web Worker.
• Invalid language / non-positive timeout throw typed ConfigError / SandboxError.
• Dispose is idempotent; execute after dispose fails clearly.

#Minimal example

import { sandboxTool, createMandatorySandbox } from '@agentskit/sandbox'
import { filesystem, webSearch } from '@agentskit/tools'

const codeExecution = sandboxTool({ apiKey: process.env.E2B_API_KEY })

const policy = createMandatorySandbox({
  sandbox: codeExecution,
  policy: { requireSandbox: ['code_execution'], deny: ['filesystem'] },
})

const safeTools = [codeExecution, filesystem({ basePath }), webSearch()].map(t => policy.wrap(t))

#Related

• @agentskit/tools — tools to wrap.
• Sandbox deep dive
• Mandatory sandbox

#Source

• npm: https://www.npmjs.com/package/@agentskit/sandbox
• repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/sandbox