Some work needs a **real browser**. Examples are a login to a vendor portal, form entry, clicks in client-rendered UI, and pages that [`web_fetch`](/builtin-tools#web_fetch) and [`web_search`](/builtin-tools#web_search) cannot reach.

Nakama agent-browser keeps you in the same chat or automation. The agent drives an interactive browser on the server through the [`bash`](/builtin-tools#bash) tool.

How the system works:

- The user talks to Nakama
- Nakama matches the opt-in `agent-browser` skill when the task needs interaction or a login
- The agent runs [agent-browser](https://github.com/vercel-labs/agent-browser) CLI commands through `bash`
- Snapshots return a compact accessibility tree with short refs like `@e2`
- This tree uses fewer tokens than raw HTML
- The agent clicks and fills fields by those refs. Then the agent closes the browser when the task ends

The product has no dedicated `browser` builtin. The workflow is **`bash` + the `agent-browser` skill + the host CLI** and Chrome.

## Why use agent-browser

| Need | Prefer |
|------|--------|
| Public page text / Markdown | [`web_fetch`](/builtin-tools#web_fetch) |
| JS-heavy public page (no login) | Firecrawl scrape, when the profile has the preinstalled [firecrawl](/mcp#example-firecrawl) MCP server |
| Discover sources on the open web | [`web_search`](/builtin-tools#web_search) |
| Login walls, forms, clicks, client-rendered UI | **`agent-browser` skill + `bash`** |

Use agent-browser when the site has no usable API. The agent must act like a person in a browser. One example is an order status check on an e-commerce portal after a login.

## How the pieces fit together

| Piece | Role |
|-------|------|
| **`agent-browser` skill** | Opt-in bundled skill. The skill teaches when and how to drive the CLI |
| **`bash` tool** | Runs `agent-browser` commands in the profile workspace |
| **Profile Config → Skills** | Assign the skill. **Install** the CLI and Chrome on the server. **Add bash** when needed |
| **Host CLI + Chrome** | Install through the dashboard **Install** button or manually on the Nakama server |
| **CloakBrowser (optional)** | Host env `AGENT_BROWSER_EXECUTABLE_PATH` / `AGENT_BROWSER_ARGS`. Not in the Docker image |

```text
User message (interactive task or login wall)
  → skill matcher activates agent-browser
  → Nakama agent calls bash with agent-browser commands
  → Same daemon session for open → snapshot → click/fill in that run
  → agent-browser close
  → Nakama agent summarizes the result
```

## Setup

### 1. Assign the skill from the profile Config tab

Platform admins:

1. Open **Agent → Profiles**. Select the profile. Open the **Config** tab.
2. In **Skills**, open the skill picker. Find **`agent-browser`**.
3. If the skill is blocked, use the buttons in that row or banner:
   - **Install** — installs the `agent-browser` CLI and Chrome on this Nakama server
   - **Add bash** — assigns the `bash` tool to the profile. Super Bot usually has bash already.
4. Assign the **`agent-browser`** skill after install and bash are ready.

The skill is opt-in. Nakama does not auto-assign it to Super Bot or default profiles. The profile needs **bash** and the skill. The skill alone cannot open a browser.

### 2. Manual CLI install (optional)

If the dashboard **Install** button is not available or fails, install on the host where the Nakama `bash` tool runs:

```bash
npm install -g agent-browser
agent-browser install
```

On Linux, if Chrome libraries are missing:

```bash
agent-browser install --with-deps
```

Then open the profile **Config** tab. Assign the skill. Use **Add bash** if needed.

### 3. Optional: CloakBrowser for antibot sites

Stock Chrome from `agent-browser install` is enough for most portals. Some login-walled sites block that Chrome. [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) is a patched Chromium you can point agent-browser at **on the Nakama host**. Nakama does not ship Cloak and does not make it the default.

1. Install Cloak on the same machine that runs `bash` (not inside the agent chat):

```bash
pip install cloakbrowser
python -m cloakbrowser install
python -m cloakbrowser info
```

Node installs work the same way: `npx cloakbrowser install` then `npx cloakbrowser info`.

2. Set host environment variables for the Nakama process. `bash` inherits `process.env`, so agent-browser picks these up without a Nakama setting:

```bash
export AGENT_BROWSER_EXECUTABLE_PATH="/path/from/cloakbrowser/info"
export AGENT_BROWSER_ARGS="<copy from Cloak's agent-browser example>"
```

The stealth argument list lives in Cloak's [agent-browser integration](https://github.com/CloakHQ/CloakBrowser/blob/main/examples/integrations/agent_browser.sh). Copy it. Do not invent flags.

3. Restart Nakama so the process sees the new env. Leave both variables unset to keep stock Chrome.

Docker: the official image does not include Cloak. Bind-mount the Cloak binary into the container and pass the same env vars, or run Nakama on the host. See [Docker](/docker).

### 4. Try it in chat

Ask the profile for a task that needs a real browser. Example:

> Open our vendor portal, log in with the credentials I provide, and tell me the status of the latest order.

Or force the skill:

```text
/skill agent-browser Check https://example.com and summarize the main heading
```

The same path works in **automations**. The automation profile needs bash and the skill. The host CLI must be installed.

## How a typical run works

In **one** chat turn or automation run:

1. **Open** a URL. Or launch the browser, then go to the URL.
2. **Snapshot** the page (`snapshot -i`) to get element refs (`@e1`, `@e2`, …).
3. **Act** — do `click`, `fill`, and `press`. Wait when needed. Use those refs. Take a new snapshot after large UI changes.
4. **Screenshot** (optional) under the profile workspace `artifacts/` directory.
5. **Close** the browser when the task ends.

Across runs, sessions are **fresh** by default. The product does not keep sticky cookies or a restored login state. The agent logs in again in the run when the task needs it.

## Credentials and safety

- Use credentials that the user supplies in the prompt. You can also use credentials that are already known for that task.
- Do not expect Nakama to store site passwords for agent-browser in v1.
- Agents must not echo passwords in summaries. Agents must not take screenshots of password fields.
- Viewers cannot invoke agents. Viewers cannot start browser runs.

## Troubleshooting

| Symptom | What to examine |
|---------|-----------------|
| Agent never opens a browser | Is `agent-browser` assigned? Does the message look like interactive work or a login wall? Try `/skill agent-browser …` |
| `command not found` / `ENOENT` | Use **Install** on the profile Config → Skills picker, or install manually (`npm install -g agent-browser && agent-browser install`) |
| Skill assigned but nothing runs | The profile also needs **`bash`**. Use **Add bash** in the skill picker if the UI shows the prompt |
| Clicks miss or fail after navigation | The agent must take a **fresh snapshot** before it uses refs again |
| Daemon seems stuck | Ask the agent to run `agent-browser close` or `agent-browser close --all`. Or run `agent-browser doctor` |
| Site still blocks the browser | Stock Chrome may be fingerprinting as automation. Install Cloak on the host and set `AGENT_BROWSER_EXECUTABLE_PATH` / `AGENT_BROWSER_ARGS` as in [Optional: CloakBrowser](#3-optional-cloakbrowser-for-antibot-sites) |
| Cloak set but Chrome for Testing still launches | Confirm the env is on the **Nakama process**, then restart. `bash` inherits host env; a one-off shell on your laptop does not change the server |

## Next steps

- [Skills](/skills) — bundled skills catalog and assignment
- [Builtin tools](/builtin-tools#bash) — `bash` parameters and availability
- [Coding agent](/coding-agent) — similar bash and skill pattern for repo coding work
- [agent-browser](https://github.com/vercel-labs/agent-browser) — upstream CLI reference