agent-browser requires an Eve sandbox. Configure…

Error message

agent-browser requires an Eve sandbox. Configure agent/sandbox.ts first.

What it means

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.

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

Example fix

// before
await runAgentBrowser({ getSandbox: async () => null }, ["tab"]); // throws

// after
const sandbox = await ctx.getSandbox();
if (sandbox === null) throw new Error("configure agent/sandbox.ts");
await runAgentBrowser(ctx, ["tab"]);

Defensive patterns

Strategy: validation

Validate before calling

const sandbox = await ctx.getSandbox();
if (sandbox === null) {
  throw new Error("agent-browser unavailable: no eve sandbox configured.");
}
const result = await runAgentBrowser(ctx, args);

Type guard

function isEveToolContext(ctx: unknown): ctx is EveToolContext {
  return typeof (ctx as EveToolContext)?.getSandbox === "function";
}

Prevention

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

When it happens

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

Common situations: Custom tool wrappers around runAgentBrowser that forget sandbox wiring; test doubles returning null; refactors of the eve context type.

Related errors

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

Appendix: source

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

          command,
          exitCode: result.exitCode,
          stderr: result.stderr,
          stdout: result.stdout,
        }),
      ),
    );
  }
  return results;
}

export async function runAgentBrowser<TJson = unknown>(
  ctx: EveToolContext,
  args: AgentBrowserArgs,
  options: EveRunAgentBrowserOptions = {},
): Promise<AgentBrowserCommandResult<TJson>> {
  const sandbox = await ctx.getSandbox();
  if (sandbox === null) {
    throw new Error("agent-browser requires an Eve sandbox. Configure agent/sandbox.ts first.");
  }

  const session = options.session ?? defaultSessionName(options.sessionPrefix ?? "eve", sandbox.id);
  const command = buildAgentBrowserCommand(args, { ...options, session });
  const result = await sandbox.run({ abortSignal: options.abortSignal, command });

  return throwIfCommandFailed(
    createAgentBrowserCommandResult<TJson>({
      command,
      exitCode: result.exitCode,
      stderr: result.stderr,
      stdout: result.stdout,
    }),
  );
}

export function buildAgentBrowserCommand(
  args: AgentBrowserArgs,

View on GitHub (pinned to f9a6cc3421)