{"record":{"id":"945cfc861a5d8c23","repo":"vercel-labs/agent-browser","slug":"the-browser-tools-require-an-eve-sandbox-configur","errorCode":null,"errorMessage":"The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.","messagePattern":"The browser tools require an eve sandbox\\. Configure agent/sandbox\\.ts in the consuming agent\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@agent-browser/eve/extension/lib/browser.ts","lineNumber":97,"sourceCode":"    exitCode: raw.exitCode,\n    stderr: raw.stderr,\n    stdout: raw.stdout,\n  });\n\n  const envelope = result.json;\n  if (envelope !== null && envelope.success === false) {\n    throw new Error(`agent-browser ${args[0] ?? \"\"} failed: ${envelope.error ?? \"unknown error\"}`);\n  }\n  if (result.exitCode !== 0) {\n    throw new AgentBrowserCommandError(result);\n  }\n  return (envelope?.data ?? null) as TData;\n}\n\nasync function requireSandbox(ctx: BrowserToolContext): Promise<EveSandboxSession> {\n  const sandbox = await withDeadline(ctx.getSandbox(), \"The sandbox session\");\n  if (sandbox === null || sandbox === undefined) {\n    throw new Error(\n      \"The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.\",\n    );\n  }\n  return sandbox;\n}\n\nasync function ensureInstalled(sandbox: EveSandboxSession, abortSignal?: AbortSignal): Promise<void> {\n  if (!extension.config.autoInstall) {\n    return;\n  }\n  let pending = pendingInstalls.get(sandbox.id);\n  if (pending === undefined) {\n    pending = installIfMissing(sandbox, abortSignal);\n    pendingInstalls.set(sandbox.id, pending);\n    // Let the next tool call retry a failed install instead of replaying the rejection.\n    pending.catch(() => pendingInstalls.delete(sandbox.id));\n  }\n  await pending;","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/eve/extension/lib/browser.ts#L79-L115","documentation":"requireSandbox in the eve extension wraps ctx.getSandbox() with a 180s deadline and rejects null/undefined. Eve tools execute shell commands through a sandbox session; if the consuming agent never wired one up (agent/sandbox.ts), every browser tool call fails here before any CLI command runs.","triggerScenarios":"Using the @agent-browser/eve extension in an agent whose tool context returns null from getSandbox(); misconfigured agents that skip the sandbox module; sandbox factory throwing and being swallowed into null.","commonSituations":"Copying the extension into a new eve agent without porting agent/sandbox.ts; renames/refactors breaking the getSandbox binding; running tools outside a sandboxed environment.","solutions":["Implement agent/sandbox.ts in the consuming agent so ctx.getSandbox() resolves to an EveSandboxSession","Return the session from the agent's context wiring before registering the browser tools","Check for a swallowed error in your getSandbox implementation — resolve the session, never null, in healthy setups"],"exampleFix":"// before\nconst ctx = { getSandbox: async () => null }; // tools throw\n\n// after\nimport { createSandbox } from \"./sandbox\";\nconst sandbox = createSandbox();\nconst ctx = { getSandbox: async () => sandbox }; // resolves EveSandboxSession","handlingStrategy":"validation","validationCode":"const sandbox = await ctx.getSandbox();\nif (sandbox === null || sandbox === undefined) {\n  throw new Error(\"Browser tools unavailable: configure agent/sandbox.ts before use.\");\n}","typeGuard":"function hasSandbox(ctx: BrowserToolContext): Promise<boolean> {\n  return Promise.resolve(ctx.getSandbox()).then((s) => s != null);\n}","tryCatchPattern":null,"preventionTips":["Wire agent/sandbox.ts in every agent that registers the browser tools","Add a startup smoke test that calls getSandbox() once when the agent boots","Never swallow errors inside your getSandbox implementation — resolve or throw, not null"],"tags":["eve","sandbox","configuration","setup"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}