Mandatory sandbox

Without explicit constraints, a tool-calling agent can invoke dangerous tools with arbitrary arguments. createMandatorySandbox (from @agentskit/sandbox) wraps each tool with a policy layer — calls that match the deny list, miss the allow list, or fail a validator are rejected before execution.

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

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

const mandatory = createMandatorySandbox({
  sandbox: codeExecution,
  policy: {
    allow: ['code_execution', 'web_search'],
    deny: ['filesystem'],
    requireSandbox: ['code_execution'],
    validators: {
      code_execution: (args) => {
        if (typeof args.code === 'string' && args.code.length > 10_000) {
          throw new Error('code too long')
        }
      },
    },
  },
})

const tools = [codeExecution, filesystem({ basePath: './workspace' }), webSearch()].map((t) =>
  mandatory.wrap(t),
)

#Modes

#requireSandbox semantics

When a tool is in requireSandbox, its original execute body is not run. Arguments are delegated to the shared sandbox tool's execute. This is a routing shim for code-execution style tools — it does not transparently wrap arbitrary tool implementations while still calling them.

Policy arrays/records are snapshotted at createMandatorySandbox time so later caller mutations cannot widen allow/deny/require decisions.

#Sandbox backends

• E2B (optional peer @e2b/code-interpreter) — default cloud path
• Web Worker (@agentskit/sandbox/web) — browser thread + DOM isolation only; not WebContainer
• Custom SandboxBackend — Docker, Firecracker, etc.
• Local runtimes — process / seatbelt / bwrap / docker for host-process isolation

See the sandbox deep dive.

#Related

• Sandbox deep dive
• HITL