The browser is a real web browser an Agent can open when a task calls for it. It runs in your own Browserbase project, one browser per session, and is destroyed when the session ends. Where a connection hands an Agent an API and the coding sandbox hands it a filesystem, the browser lets it look at a website the way a person would: open a page, read it, click through it, and show you what it saw. This page covers connecting Browserbase, what Agents can do with the browser, the proof they can attach, and the limits.
Prerequisites
- The Owner or Admin role in Chickpea. Settings → Browser is an install-wide setting.
- A Browserbase project. Any plan works. The free plan includes one browser hour a month. Sign-in hand-offs keep a browser open for a person, which needs a paid Browserbase plan.
The browser works on Cloudflare and on Node alike, because the browser itself runs at Browserbase, not in your deployment.
Connect Browserbase
Create a Browserbase project
Sign up at browserbase.com, or open an existing project.
Copy the project's API key
In Browserbase, open Settings → API keys and copy the key.
Paste it in Chickpea
In Admin, open Settings → Browser, paste the key, and select Connect. Chickpea checks the key with Browserbase before storing it, and never shows it again.
If Browserbase does not accept the key, the card says so: “That key was not accepted by Browserbase. Copy it again from Settings → API keys.”
Paste the key only into Settings → Browser. Never paste it into a Slack message or a chat with a coding agent.
Verify
The section’s badge reads Ready, and the card shows Connected · key ending … with the last four characters of your key. Below it, the card lists:
| Row | What it shows |
|---|---|
| Browser time this month | Hours and minutes of browser time Agents used this calendar month |
| Sessions this month | How many browser sessions were opened this month |
| Where the browser runs | One browser per session, destroyed afterwards |
| Recordings kept at Browserbase for | 30 days |
Then ask an Agent for something only a live page can answer:
@researchwhat does the pricing page on example.com say about the team plan today?
The Agent opens the page and answers with what the page showed, including its address.
Nothing is enabled per Agent. Once Browserbase is connected, every Agent can open public websites when a task calls for it.
What an Agent can do
An Agent decides when to browse. It opens a page when the answer depends on what a live website shows right now: a current price, a page’s wording, whether a link or a flow works, or how a page looks. For a general question where the live page adds nothing, it answers from what it knows.
- Open a page. From a full address, or from plain words, which runs a web search and picks a result.
- Read it. The Agent reads the page’s text and structure, not just a picture of it.
- Click, type, and scroll. It follows links, uses search boxes, picks options, and moves through a page. On public websites this is read-only: the Agent navigates but does not submit anything that changes data.
- Look at it. For questions text cannot answer, such as layout, images, charts, or whether something looks broken, it examines the page visually.
- Sign in. Only to websites you grant it on its Websites tab. See Website logins.
Proof: screenshots and recordings
Every browser session is recorded at Browserbase. An Agent can attach proof to its reply when proof helps you:
- A screenshot of the page, when something looks wrong or you asked to see it.
- The session recording as an MP4, when it exercised a multi-step flow or claims that something works or is broken.
Nothing attaches automatically; the Agent chooses. When a file cannot be attached, the Agent says so and describes what it saw instead.
Recordings stream straight to Slack on both the shared Slack app and your own Slack app, up to Slack’s 1 GB file limit; a recording runs at roughly 250 KB/s, so even a full ten-minute session (about 150 MB) attaches. The full recording also stays in your Browserbase project for 30 days.
Limits
| Limit | Value |
|---|---|
| Browser time per reply | 10 minutes. When it is spent, the Agent answers with what it found so far. |
| Browsers per session | 1, destroyed when the session ends |
| Recording kept at Browserbase | 30 days |
| Attached file (screenshot or recording) | 1 GB (Slack’s limit) |
| Browserbase free plan | 1 browser hour a month |
Safety
- Pages are data, not instructions. Anything a website says is treated as untrusted content. Text on a page that tells the Agent to do something, go somewhere, or reveal something is ignored.
- No typed credentials. An Agent never types passwords, codes, payment details, or personal data into a website itself. Signing in happens only through a website login you granted, and Chickpea types those values, not the Agent.
- Changes need your approval. Public sites and check-only logins are read-only. On a login allowed to take actions, the Agent asks before every step that changes data. See Actions and approval.
Replace the key or disconnect
In Settings → Browser, Replace key opens the same paste field; the new key is checked before it replaces the old one. Disconnect asks you to confirm, then removes the key. Agents cannot open a browser until a key is connected again. Saved website logins stay on their Agents.
Deployment-owned key
An operator can supply the key through the environment instead: set BROWSERBASE_API_KEY, and optionally BROWSERBASE_PROJECT_ID, on the Worker or the Node process. The environment value wins over a key stored in Admin, and the card becomes read-only, naming the variable, so the key is changed there rather than in Admin.
Next steps
- Website logins: let an Agent sign in to a website, hand the sign-in to a person, and approve actions.
- Security model: how credentials and authority are handled on every turn.