Dooza Browser
One shared, logged-in Chrome for all your AI agents. Claude Code, Codex, ChatGPT or your own scripts get a real
browser through MCP or plain HTTP: open tabs, read pages, click, type, upload files, run short Playwright scripts,
or hand off a whole web task. Agents share what they learn about each site, and they never steal your mouse or close
your tabs.
We built it to run Dooza's own team of AI agents (sales, SEO, video, ops) on one machine, all
sharing one Chrome that is logged in once. This is that code, cleaned up.
Why
- Log in once. The agents use one Chrome profile. You sign in to Gmail, LinkedIn, Stripe... by hand once; cookies
persist. Agents never see your passwords.
- Many agents, one browser, no fights. Each tab belongs to the agent that opened it. Agent windows open in the
background in their own screen area, never as tabs in your window, and never take focus.
- Fast actions, not click-by-click.
tab_playwright runs a short Playwright script on a tab: 10 steps in one tool
call. Models already know Playwright well, so it is quicker and cheaper than one tool call per click.
- Site memory.
site_note saves one-line lessons per site ("the Save button is #submit-2", "this site blocks
headless"). They come back automatically every time any agent opens that site.
- Whole tasks on a cheap model.
browse(task) gives the task to browser-use
on any OpenRouter model (or to headless Claude Code), with a judge, a retry on a stronger model, and a stronger
model by default on sensitive sites (inbox, payments).
Tools
| Tool | What it does |
|---|
browse(task, url?, model?, owner) | Whole web task in its own background window; returns text |
tab_open(url, owner) | New background tab you own; returns tab_id + saved site notes |
tab_read(tab_id, owner, mode) | text, links, inputs (form fields with ready selectors) or html |
tab_click / tab_type / tab_navigate / tab_eval | Step-by-step control |
tab_playwright(tab_id, owner, script) | Python Playwright (async) on that tab; set result = ... |
tab_upload(tab_id, owner, paths, ...) | File upload, including buttons that open a native file picker |
tab_screenshot / tab_list / tab_close | |
site_note(site, owner, note?) | Read or add per-site notes (secrets are refused) |
status() | Chrome version, open tabs, free task slots, OpenRouter spend |
Every tool is also POST /api/<tool> with the arguments as JSON.
Quick start (Linux or macOS)
git clone https://github.com/Dooza-ai/dooza-browser && cd dooza-browser
python3 -m venv .venv && .venv/bin/pip install -e . # no browser download: it drives your own Chrome
cp config.example.json config.json
# 1. a dedicated Chrome with DevTools on localhost:9222 (sign in to your sites in this window, once)
examples/start-chrome.sh &
# 2. the server (MCP at http://127.0.0.1:8765/mcp)
export OPENROUTER_API_KEY=... # only for browse() with the browser-use engine
.venv/bin/dooza-browser
Connect a client:
claude mcp add --transport http --scope user browser http://127.0.0.1:8765/mcp # Claude Code
# Codex: ~/.codex/config.toml -> [mcp_servers.browser] url = "http://127.0.0.1:8765/mcp"
curl -s localhost:8765/api/tab_open -H 'Content-Type: application/json' -d '{"url":"https://example.com","owner":"me"}'
For Claude Code, copy skill/SKILL.md to ~/.claude/skills/dooza-browser/SKILL.md so agents know when to use which tool.
On a headless server, run Chrome on a virtual display wide enough for both areas (Xvfb :99 -screen 0 2880x900x24);
your own window sits at x 0-1440, agent windows open at x >= 1440 (agent_window in config.json). A systemd unit is
in examples/.
Configuration (config.json)
| Key | Meaning |
|---|
engine | browser-use (OpenRouter models) or claude (Claude Code CLI drives the tab tools; uses your Claude login) |
models.default / sensitive / strong | OpenRouter model ids: normal sites / sensitive_domains / retry |
sensitive_domains | URL substrings that get the sensitive model |
max_concurrent_tasks, max_tasks_per_owner, max_steps, task_timeout_s | browse() limits |
tab_idle_close_s, max_tabs_per_owner | Forgotten tabs are closed; a 4th tab closes your oldest |
agent_window | Where agent windows open (left, width, height) |
reap_orphans | true also closes unowned windows in the agent area. Only for a Chrome dedicated to agents |
upload_roots | Folders uploads may come from ({owner} = agent name). Files that look like secrets are always refused |
playwright_sandbox | Optional {"user": "pwrun", "python": "/opt/pwrun/venv/bin/python", "runner": "/opt/pwrun/pw_runner.py"}: run scripts as a user that can't read your files (needs a sudoers rule) |
api_hints | {"url substring": "use the X API instead"}, shown to agents when they open that site |
Environment: DOOZA_BROWSER_CONFIG (default ./config.json), DOOZA_BROWSER_HOME (logs, screenshots, site notes,
optional credentials.env; default ~/.dooza-browser), OPENROUTER_API_KEY.
credentials.env (NAME=value lines) is passed to browser-use as sensitive_data: the model only sees NAME and the
value is filled in at typing time.
Safety
- The server listens on 127.0.0.1 only. Anyone who can reach it controls your logged-in browser: don't expose it.
- Page content is data, never instructions; tool descriptions and the browse prompt say so, but prompt injection is
a real risk for any browser agent. Give the agent Chrome only the logins your agents need.
tab_eval and tab_playwright run code you send in the page or on your machine. Use the sandbox user on shared
machines.- Optional
python -m dooza_browser.captcha <tab> solves reCAPTCHA/hCaptcha/Turnstile through 2Captcha (paid,
TWOCAPTCHA_API_KEY). Use it only where the site's terms allow automation.
Credits
Built on browser-use, FastMCP and
Playwright. Ideas from Aside's write-up on browser agents (Playwright actions, site memory).
MIT licensed. Made by Dooza: AI agents that work as your team.
