Agent Browser

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 and 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 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 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

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

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:

npm install -g agent-browser
agent-browser install

On Linux, if Chrome libraries are missing:

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 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):

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:

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. 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.

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:

/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

Next steps

• Skills — bundled skills catalog and assignment
• Builtin tools — bash parameters and availability
• Coding agent — similar bash and skill pattern for repo coding work
• agent-browser — upstream CLI reference