# Browserman

> Use BrowserMan when an agent needs the user's real browser environment, optimized official scripts, or Agent-authored/community scripts running through BrowserMan's standard context.

- Skill: `browserman-run/browserman` (Agent Skill)
- Install (CLI): `npx skillmds@latest add browserman-run/browserman`
- Raw SKILL.md: https://api.skillmd.com/api/skills/browserman-run/browserman/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: browserman-run (https://skillmd.com/u/browserman-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/browserman-run/browserman

---


# BrowserMan

BrowserMan gives the agent access to the user's real browser environment.

Use BrowserMan when the task depends on:
- the user's existing login session
- real browser state, tabs, cookies, or extension-connected context
- BrowserMan's site-optimized automation scripts
- user-authored or community automation scripts that run on the Agent machine
- delegated browser access that the user can approve and revoke

Do not ask the user for BrowserMan email/password in chat.
Do not tell the user to register through an API.
Do not lead with fallback API keys.

## When to use your native browser tool vs BrowserMan

Prefer your native or default browser tool when:
- the page is public
- no user login or session is required
- the task is simple browsing, reading, or lightweight interaction
- you do not need the user's real browser state

Prefer BrowserMan when:
- the task depends on the user's real logged-in browser session
- you need access to the user's actual browser state, cookies, tabs, or extension-connected browser
- BrowserMan provides a matching optimized script for the target site
- the native browser tool is not reliable enough for the authenticated flow
- the user has explicitly approved BrowserMan access for this task pattern

Tool selection order:
1. If your native/default browser tool is enough for a public, non-authenticated task, use it first.
2. If the task needs the user's real browser session or BrowserMan has a matching optimized script, use BrowserMan.
3. Inside BrowserMan, check scripts first.
4. If no official script matches, inspect or create a reusable Agent-local script.
5. Use low-level BrowserMan page commands to explore unfamiliar pages or handle genuinely one-off recovery.

## Recommended setup

After installing this skill, proactively complete BrowserMan setup before trying to use BrowserMan for a real task.

Naming rule:
- npm package: `browserman-cli`
- installed executable and documented command: `browserman`
- one-off npx uses the package name with latest version, for example `npx -y browserman-cli@latest setup`

Recommended path:

```bash
npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version
browserman setup
browserman doctor
```

Version requirement:
- Use the latest BrowserMan CLI unless the user explicitly asks for an older version.
- Require `browserman` version `0.4.0` or newer for Agent-local script commands.
- If `browserman script inspect`, `browserman script describe-local`, or `browserman script run --local` is missing, the installed CLI is stale. Upgrade before continuing:

```bash
npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version
```

Fallback if BrowserMan CLI is not globally available:

```bash
npx -y browserman-cli@latest setup
npx -y browserman-cli@latest doctor
```

If the user already has an approval code, the direct variation is:

```bash
npx -y browserman-cli@latest setup --code <bm_agreq_...>
```

BrowserMan stores delegated local config at:

```text
~/.browserman/config.json
```

Treat that file as the local source of truth for:
- serverUrl
- token
- tokenType
- browserId
- browserIds
- browserScopeMode
- capabilities

## Preferred BrowserMan interface order

Use BrowserMan in this order:
1. BrowserMan CLI
2. Raw BrowserMan HTTP only if CLI is unavailable

Prefer commands like:

```bash
browserman browser list --json
browserman browser current --json
browserman browser ping --json
browserman page open --url https://example.com --json
browserman page read --json
browserman page click --ref 12 --json
browserman page type --text "hello" --json
browserman page press --key Enter --json
browserman page screenshot --out ./page.png --json
browserman script list --json
browserman script actions --platform x --json
browserman script describe --platform x --action search --json
browserman script run --platform x --action search --text "browserman" --json
browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json
browserman script run --local ./my-script --action read --json
browserman execution wait <executionId> --json
```

If BrowserMan is only available through npx in the current environment, use the package name with `@latest` before the subcommand, for example `npx -y browserman-cli@latest setup` or `npx -y browserman-cli@latest script list --json`.

## Capability-scoped tokens

Delegated tokens can be scoped by capability.

Important capabilities:
- `observe` — browser listing, status, ping, execution reads, page inspection
- `commands` — navigate, click, type, press, run_script, low-level browser control
- `browserManagement` — browser creation, update, delete, and other management operations

When a BrowserMan call returns 403:
- do not assume the token is invalid
- first suspect missing capability or browser out of scope
- ask the user to re-approve in BrowserMan if needed

## Required execution order

Always follow this order.

### Step 0: Check the BrowserMan script catalog first

Before low-level browser control, discover scripts in small steps:

```bash
browserman script list --json
browserman script actions --platform <platform-id> --json
browserman script describe --platform <platform-id> --action <action> --json
```

Use canonical platform ids such as `x`, `forem`, `amazon`, `taobao`, `zhihu`, `producthunt`, or `medium`. Do not use domains as platform ids. Domains such as `x.com`, `dev.to`, or `amazon.co.jp` are aliases or runtime targets, not the `--platform` value.

If a matching platform/action exists, prefer `browserman script run`.

### Step 1: Confirm browser availability with ping

Before real work, verify the chosen browser is reachable:

```bash
browserman browser ping --json
```

If this returns offline or 503, the browser is not currently connected.

### Step 2A: If a script matches, run it

Examples:

```bash
browserman script run --platform x --action search --text "browserman" --json
browserman script run --platform forem --base-url https://dev.to --action get_feed --json
browserman script run --platform amazon --marketplace jp --action search --query "keyboard" --json
```

If `script run` returns an `executionId`, verify completion before reporting success:

```bash
browserman execution wait <executionId> --json
```

### Step 2B: If no official script matches, create or reuse a local script

Agent-local scripting is the normal BrowserMan extensibility path. Use low-level page commands to discover the site, then save stable logic in `browserman.script.js` or `index.js` so the same Agent or other Agents can reuse it.

Inspect community code before execution:

```bash
browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json
```

Run it against the approved real browser:

```bash
browserman script run \
  --local ./my-script \
  --action read \
  --browser <browser-name> \
  --params-json '{}' \
  --json
```

Script example:

```js
import { defineScript } from 'browserman-cli/scripts';

export default defineScript({
  id: 'community.page-details',
  name: 'page-details',
  version: '1.0.0',
  apiVersion: '^1.0.0',
  actions: {
    read: {
      params: { type: 'object', properties: {} },
      async run(ctx) {
        const [title, location] = await Promise.all([
          ctx.evaluate('document.title'),
          ctx.getUrl(),
        ]);
        return { title, url: location?.url || String(location || '') };
      },
    },
  },
});
```

The action signature is `(ctx, params)`. Official server scripts and Agent-local scripts share the same CTX methods. BrowserMan reserves the browser, renews an execution lease, records the result, cleans the session, and releases the browser.

Local/community scripts have the user's local Node.js permissions, like npm dependencies. Review and trust source before running it. Do not upload arbitrary community Node.js code to the BrowserMan server.

### Step 2C: Use low-level page commands for exploration or one-off recovery

Recommended low-level sequence:
1. `browserman page open --url ... --json`
2. `browserman page read --json`
3. `browserman page click` / `browserman page type` / `browserman page press`
4. `browserman page read --json` again after page changes
5. `browserman page screenshot --out ./page.png --json` or `browserman page url --json` to verify state

For recurring or shareable workflows, convert the proven low-level sequence into a local script instead of repeatedly shelling out to `browserman page ...` from inside JavaScript.

## Destructive-action checklist

Before performing destructive or externally visible actions, confirm intent with the user.

Examples:
- delete
- purchase
- submit
- post
- publish
- send message
- irreversible settings changes

Especially confirm before:
- clicking destructive UI
- running BrowserMan scripts that post, delete, or change account state
- low-level form submission that causes side effects

## What not to do

Do not:
- ask the user for BrowserMan email/password in chat
- tell the user to register through an API endpoint
- tell the user to create a fallback key as the default onboarding path
- assume every browser is in scope for the delegated token
- assume every delegated token has `commands`
- skip the script-catalog check
- run unreviewed community JavaScript
- hand-write a separate incompatible CTX
- use repeated `browserman page ...` subprocesses as the script runtime
- assume Agent-local scripts bypass BrowserMan execution ownership