agent-browser requires an Eve sandbox. Configure agent/sandb

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.

Source

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

          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 548b159b30)

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@548b159b30 (2026-08-16). Data as JSON: /api/errors/eaa7693c536cad7b. Report an issue: GitHub.