The browser tools require an eve sandbox. Configure agent/sa

Error message

The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.

What it means

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.

Source

Thrown at packages/@agent-browser/eve/extension/lib/browser.ts:97

    exitCode: raw.exitCode,
    stderr: raw.stderr,
    stdout: raw.stdout,
  });

  const envelope = result.json;
  if (envelope !== null && envelope.success === false) {
    throw new Error(`agent-browser ${args[0] ?? ""} failed: ${envelope.error ?? "unknown error"}`);
  }
  if (result.exitCode !== 0) {
    throw new AgentBrowserCommandError(result);
  }
  return (envelope?.data ?? null) as TData;
}

async function requireSandbox(ctx: BrowserToolContext): Promise<EveSandboxSession> {
  const sandbox = await withDeadline(ctx.getSandbox(), "The sandbox session");
  if (sandbox === null || sandbox === undefined) {
    throw new Error(
      "The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.",
    );
  }
  return sandbox;
}

async function ensureInstalled(sandbox: EveSandboxSession, abortSignal?: AbortSignal): Promise<void> {
  if (!extension.config.autoInstall) {
    return;
  }
  let pending = pendingInstalls.get(sandbox.id);
  if (pending === undefined) {
    pending = installIfMissing(sandbox, abortSignal);
    pendingInstalls.set(sandbox.id, pending);
    // Let the next tool call retry a failed install instead of replaying the rejection.
    pending.catch(() => pendingInstalls.delete(sandbox.id));
  }
  await pending;

View on GitHub (pinned to 548b159b30)

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

Example fix

// before
const ctx = { getSandbox: async () => null }; // tools throw

// after
import { createSandbox } from "./sandbox";
const sandbox = createSandbox();
const ctx = { getSandbox: async () => sandbox }; // resolves EveSandboxSession

Defensive patterns

Strategy: validation

Validate before calling

const sandbox = await ctx.getSandbox();
if (sandbox === null || sandbox === undefined) {
  throw new Error("Browser tools unavailable: configure agent/sandbox.ts before use.");
}

Type guard

function hasSandbox(ctx: BrowserToolContext): Promise<boolean> {
  return Promise.resolve(ctx.getSandbox()).then((s) => s != null);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of vercel-labs/agent-browser@548b159b30 (2026-08-16). Data as JSON: /api/errors/945cfc861a5d8c23. Report an issue: GitHub.