Five AI agent browser recipes you can run today

The quickest way to learn how an AI agent should use a browser is to run a working example. Here are five, each a small complete project in our agent recipes: Claude Code browsing with one isolated browser per task, existing Playwright code inside a saved profile, a scheduled headless job on a server, an agent that hands a sign-in to you, and two accounts signed in side by side without sharing a cookie. Each of these five was run end to end on 12 November 2026, against our own demo pages, example.com and example.org.

For each one you get the goal, the setup, and the safety settings that belong with it. The code lives in the public browz-agent-recipes repository as well as on the recipes page.

Before you start

Install Browz from the download page and open it. Each Browz profile is a complete, separate browser with its own fingerprint, proxy, cookies and storage, and the recipes give your agent or script one of them. The local MCP server and the Local API read the app's own token from its data folder, so no recipe asks you to paste one. You need Node.js 20 or later for most of them.

One rule for all five: give each agent its own key, not your master token. A key names the profiles, sites and scopes it may use, and every call it makes is logged on your computer for 90 days (agent keys).

1. Claude Code with one isolated browser per task

Goal: Claude Code opens a fresh browser for each task, reads and acts on pages, and wipes the browser when the task ends.

Setup: add the server to your project with a .mcp.json in its root:

Then add a short section to the project's CLAUDE.md telling Claude how to browse: open each task with browz_session_open, read pages with browz_snapshot, act with browz_act on the refs it returns, call browz_request_human when a snapshot says NEEDS A PERSON, and finish with browz_session_close. Run it non-interactively with only the Browz tools allowed:

Claude calls browz_session_open, browz_navigate, browz_snapshot, browz_screenshot and browz_session_close, and answers with the title "Example Domain".

Safety settings: an ephemeral session is a fresh profile that browz_session_close wipes, files and cookies included; one left open is wiped after its time to live, a day by default. Pass "proxy": "pool" to give each task its own exit. For a key of its own, set BROWZ_LOCAL_AGENT_TOKEN_FILE in the server's env.

2. Playwright over CDP in a saved profile

Goal: keep your existing Playwright code and run it inside a Browz profile, with that profile's fingerprint, proxy, cookies and storage.

Setup: the recipe creates a throwaway profile through the Local API (POST /api/v1/profile/create), starts it (POST /api/v1/browser/start), attaches with chromium.connectOverCDP() to the endpoint the start call returns, opens a page, saves a screenshot, detaches, stops the profile and removes it. Set BROWZ_PROFILE_ID to use one of your own profiles instead; it is started and stopped, never deleted.

Safety settings: attach, never launch, and use the existing context (browser.contexts()[0]), which is the profile. For reading and clicking without running script in the page, the Local API's own /api/v1/browser/snapshot and /api/v1/browser/act are there too. Playwright in a real browser profile explains the pattern step by step, with Python.

3. A scheduled headless job on a server

Goal: a job that runs every morning on a machine with no desktop, opens a fresh isolated browser for each page it checks, saves a snapshot and screenshot of each, and leaves nothing behind.

Setup: browz-mcp serve, part of Browz, runs the agent with headless profiles and serves MCP over Streamable HTTP on the machine's loopback address, behind a bearer token. On a Mac, the app bundle holds it and the app need not be open; on Linux it comes from the agent and engine package.

The recipe's run.mjs connects with the official MCP client and, for each address on its command line, opens an ephemeral session, navigates, takes a snapshot and a screenshot, then closes the session, which wipes the profile. It writes a report and exits non-zero if any page failed. The schedule/ folder has the same job for cron, a systemd timer and a macOS LaunchAgent:

Safety settings: run the job as an ordinary user, never root. Give it a key of its own rather than the server's token, limited to the profiles it creates and the sites it checks:

serve listens only on loopback. To reach it from other machines, put a TLS reverse proxy in front of it. Plan about 0.25 GB of memory per open session, plus 1 GB.

4. An agent that hands a sign-in to you

Goal: the agent meets a sign-in page, hands the live window to you, waits, and carries on in the same session once you are signed in, without ever seeing the password.

Setup: the recipe is a small MCP client that runs the local Browz server and plays the agent's part against a demo sign-in page it serves:

1. browz_profile_create, then browz_profile_start with headless: false, so there is a window.
2. browz_navigate to the sign-in page, then browz_snapshot, which flags it with NEEDS A PERSON.
3. browz_request_human with a reason, kind: "login", timeoutSec: 300 and doneWhenUrlContains: "/dashboard". Browz pauses automation, brings the window to the front, and shows a banner with I'm done and Cancel.
4. A new browz_snapshot shows "Welcome back".
5. browz_session_end with delete: true.

Safety settings: a person completes sign-ins, 2FA codes and CAPTCHAs. For sign-ins you want automated, store them in Browz and let the agent fill them by reference with browz_credential_fill; the agent gets back only "filled". Human hand-off for AI agents covers prompt design.

5. Two accounts side by side, kept apart

Goal: two profiles sign in to the same site at the same time, each to its own account, and neither sees the other's session. This is for accounts a site's terms allow: a business and a personal account, or one account per client you manage.

Setup: the recipe serves a demo shop, creates two profiles, starts both and signs each in at the same time the way a person would: POST /api/v1/browser/snapshot to read the form, POST /api/v1/browser/act to fill the field and click the button, POST /api/v1/browser/wait until the page says who is signed in. It then opens the account page in both and checks that each shows only its own account. No script runs in the page.

Safety settings: give each profile its own proxy, so the two accounts do not share an IP address. For an agent, use browz_session_open with mode: "persistent" and one identity per account, such as client-a and client-b: each identity returns to its own profile, cookies and proxy every time. Check each site's rules first; our acceptable use policy applies to agents and scripts the same as to people.

Where to go from here

The other recipes cover Cursor with a project rule, an OpenAI Agents SDK agent on the hosted MCP server, Puppeteer over CDP, the TypeScript SDK with a proxy, and the whole loop from Python with only the standard library. Setup for every AI client and framework, from Claude Desktop to LangChain and n8n, is in the integration guides. Everything here runs on every plan: Free covers 5 profiles, and paid plans start at $4.99 a month.

Frequently asked questions