{"record":{"id":"eaa7693c536cad7b","repo":"vercel-labs/agent-browser","slug":"agent-browser-requires-an-eve-sandbox-configure-a","errorCode":null,"errorMessage":"agent-browser requires an Eve sandbox. Configure agent/sandbox.ts first.","messagePattern":"agent-browser requires an Eve sandbox\\. Configure agent/sandbox\\.ts first\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@agent-browser/eve/extension/lib/sandbox.ts","lineNumber":172,"sourceCode":"          command,\n          exitCode: result.exitCode,\n          stderr: result.stderr,\n          stdout: result.stdout,\n        }),\n      ),\n    );\n  }\n  return results;\n}\n\nexport async function runAgentBrowser<TJson = unknown>(\n  ctx: EveToolContext,\n  args: AgentBrowserArgs,\n  options: EveRunAgentBrowserOptions = {},\n): Promise<AgentBrowserCommandResult<TJson>> {\n  const sandbox = await ctx.getSandbox();\n  if (sandbox === null) {\n    throw new Error(\"agent-browser requires an Eve sandbox. Configure agent/sandbox.ts first.\");\n  }\n\n  const session = options.session ?? defaultSessionName(options.sessionPrefix ?? \"eve\", sandbox.id);\n  const command = buildAgentBrowserCommand(args, { ...options, session });\n  const result = await sandbox.run({ abortSignal: options.abortSignal, command });\n\n  return throwIfCommandFailed(\n    createAgentBrowserCommandResult<TJson>({\n      command,\n      exitCode: result.exitCode,\n      stderr: result.stderr,\n      stdout: result.stdout,\n    }),\n  );\n}\n\nexport function buildAgentBrowserCommand(\n  args: AgentBrowserArgs,","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/eve/extension/lib/sandbox.ts#L154-L190","documentation":"The lower-level runAgentBrowser helper in @agent-browser/sandbox builds and runs the agent-browser shell command through ctx.getSandbox(). When that resolves to null it throws immediately: there is no shell to execute in, so no command is built. This is the same root cause as the eve extension variant, surfaced at the package layer.","triggerScenarios":"Calling runAgentBrowser(ctx, args) with an EveToolContext whose getSandbox() resolves null; embedding the helper in custom tools without providing a sandbox; partially-mocked contexts in tests.","commonSituations":"Custom tool wrappers around runAgentBrowser that forget sandbox wiring; test doubles returning null; refactors of the eve context type.","solutions":["Provide a real sandbox via the context before calling runAgentBrowser","Guard the call: resolve getSandbox yourself and skip/fail fast with a clearer message","In tests, mock getSandbox with a stub session whose run() returns fixed exitCode/stdout/stderr"],"exampleFix":"// before\nawait runAgentBrowser({ getSandbox: async () => null }, [\"tab\"]); // throws\n\n// after\nconst sandbox = await ctx.getSandbox();\nif (sandbox === null) throw new Error(\"configure agent/sandbox.ts\");\nawait runAgentBrowser(ctx, [\"tab\"]);","handlingStrategy":"validation","validationCode":"const sandbox = await ctx.getSandbox();\nif (sandbox === null) {\n  throw new Error(\"agent-browser unavailable: no eve sandbox configured.\");\n}\nconst result = await runAgentBrowser(ctx, args);","typeGuard":"function isEveToolContext(ctx: unknown): ctx is EveToolContext {\n  return typeof (ctx as EveToolContext)?.getSandbox === \"function\";\n}","tryCatchPattern":null,"preventionTips":["Construct the context with a real sandbox before wrapping runAgentBrowser in custom tools","In tests, stub getSandbox with a fake session rather than null","Keep one shared helper that validates the context so custom tools cannot forget the check"],"tags":["sandbox","configuration","typescript"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}