Browser (FluffBuzz-managed)

• Think of it as a separate, agent-only browser.
• The fluffbuzz profile does not touch your personal browser profile.
• The agent can open tabs, read pages, click, and type in a safe lane.
• The built-in user profile attaches to your real signed-in Chrome session via Chrome MCP.

​

What you get

• A separate browser profile named fluffbuzz (orange accent by default).
• Deterministic tab control (list/open/focus/close).
• Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.
• Optional multi-profile support (fluffbuzz, work, remote, …).

​

Quick start

fluffbuzz browser --browser-profile fluffbuzz status
fluffbuzz browser --browser-profile fluffbuzz start
fluffbuzz browser --browser-profile fluffbuzz open https://example.com
fluffbuzz browser --browser-profile fluffbuzz snapshot

​

Plugin control

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

​

Missing browser command or tool

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

​

Profiles: fluffbuzz vs user

• fluffbuzz: managed, isolated browser (no extension required).
• user: built-in Chrome MCP attach profile for your real signed-in Chrome session.

• Default: use the isolated fluffbuzz browser.
• Prefer profile="user" when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
• profile is the explicit override when you want a specific browser mode.

​

Configuration

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "fluffbuzz",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      fluffbuzz: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

​

Use Brave (or another Chromium-based browser)

fluffbuzz config set browser.executablePath "/usr/bin/google-chrome"

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}

{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}

{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}

​

Local vs remote control

• Local control (default): the Gateway starts the loopback control service and can launch a local browser.
• Remote control (node host): run a node host on the machine that has the browser; the Gateway proxies browser actions to it.
• Remote CDP: set browser.profiles.<name>.cdpUrl (or browser.cdpUrl) to attach to a remote Chromium-based browser. In this case, FluffBuzz will not launch a local browser.

• local managed profiles: fluffbuzz browser stop stops the browser process that FluffBuzz launched
• attach-only and remote CDP profiles: fluffbuzz browser stop closes the active control session and releases Playwright/CDP emulation overrides (viewport, color scheme, locale, timezone, offline mode, and similar state), even though no browser process was launched by FluffBuzz

• Query tokens (e.g., https://provider.example?token=<token>)
• HTTP Basic auth (e.g., https://user:pass@provider.example)

​

Node browser proxy (zero-config default)

• The node host exposes its local browser control server via a proxy command.
• Profiles come from the node’s own browser.profiles config (same as local).
• nodeHost.browserProxy.allowProfiles is optional. Leave it empty for the legacy/default behavior: all configured profiles remain reachable through the proxy, including profile create/delete routes.
• If you set nodeHost.browserProxy.allowProfiles, FluffBuzz treats it as a least-privilege boundary: only allowlisted profiles can be targeted, and persistent profile create/delete routes are blocked on the proxy surface.
• Disable if you don’t want it:
  • On the node: nodeHost.browserProxy.enabled=false
  • On the gateway: gateway.nodes.browser.mode="off"

​

Browserless (hosted remote CDP)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• Replace <BROWSERLESS_API_KEY> with your real Browserless token.
• Choose the region endpoint that matches your Browserless account (see their docs).
• If Browserless gives you an HTTPS base URL, you can either convert it to wss:// for a direct CDP connection or keep the HTTPS URL and let FluffBuzz discover /json/version.

​

Direct WebSocket CDP providers

• HTTP(S) discovery — http://host[:port] or https://host[:port]. FluffBuzz calls /json/version to discover the WebSocket debugger URL, then connects. No WebSocket fallback.
• Direct WebSocket endpoints — ws://host[:port]/devtools/<kind>/<id> or wss://... with a /devtools/browser|page|worker|shared_worker|service_worker/<id> path. FluffBuzz connects directly via a WebSocket handshake and skips /json/version entirely.
• Bare WebSocket roots — ws://host[:port] or wss://host[:port] with no /devtools/... path (e.g. Browserless, Browserbase). FluffBuzz tries HTTP /json/version discovery first (normalising the scheme to http/https); if discovery returns a webSocketDebuggerUrl it is used, otherwise FluffBuzz falls back to a direct WebSocket handshake at the bare root. This lets a bare ws:// pointed at a local Chrome still connect, since Chrome only accepts WebSocket upgrades on the specific per-target path from /json/version.

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• Sign up and copy your API Key from the Overview dashboard.
• Replace <BROWSERBASE_API_KEY> with your real Browserbase API key.
• Browserbase auto-creates a browser session on WebSocket connect, so no manual session creation step is needed.
• The free tier allows one concurrent session and one browser hour per month. See pricing for paid plan limits.
• See the Browserbase docs for full API reference, SDK guides, and integration examples.

​

Security

• Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
• The standalone loopback browser HTTP API uses shared-secret auth only: gateway token bearer auth, x-fluffbuzz-password, or HTTP Basic auth with the configured gateway password.
• Tailscale Serve identity headers and gateway.auth.mode: "trusted-proxy" do not authenticate this standalone loopback browser API.
• If browser control is enabled and no shared-secret auth is configured, FluffBuzz auto-generates gateway.auth.token on startup and persists it to config.
• FluffBuzz does not auto-generate that token when gateway.auth.mode is already password, none, or trusted-proxy.
• Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.
• Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.

• Prefer encrypted endpoints (HTTPS or WSS) and short-lived tokens where possible.
• Avoid embedding long-lived tokens directly in config files.

​

Profiles (multi-browser)

• fluffbuzz-managed: a dedicated Chromium-based browser instance with its own user data directory + CDP port
• remote: an explicit CDP URL (Chromium-based browser running elsewhere)
• existing session: your existing Chrome profile via Chrome DevTools MCP auto-connect

• The fluffbuzz profile is auto-created if missing.
• The user profile is built-in for Chrome MCP existing-session attach.
• Existing-session profiles are opt-in beyond user; create them with --driver existing-session.
• Local CDP ports allocate from 18800–18899 by default.
• Deleting a profile moves its local data directory to Trash.

​

Existing-session via Chrome DevTools MCP

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• The built-in user profile uses Chrome MCP auto-connect, which targets the default local Google Chrome profile.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. Open that browser’s inspect page for remote debugging.
2. Enable remote debugging.
3. Keep the browser running and approve the connection prompt when FluffBuzz attaches.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

fluffbuzz browser --browser-profile user start
fluffbuzz browser --browser-profile user status
fluffbuzz browser --browser-profile user tabs
fluffbuzz browser --browser-profile user snapshot --format ai

• status shows driver: existing-session
• status shows transport: chrome-mcp
• status shows running: true
• tabs lists your already-open browser tabs
• snapshot returns refs from the selected live tab

• the target Chromium-based browser is version 144+
• remote debugging is enabled in that browser’s inspect page
• the browser showed and you accepted the attach consent prompt
• fluffbuzz doctor migrates old extension-based browser config and checks that Chrome is installed locally for default auto-connect profiles, but it cannot enable browser-side remote debugging for you

• Use profile="user" when you need the user’s logged-in browser state.
• If you use a custom existing-session profile, pass that explicit profile name.
• Only choose this mode when the user is at the computer to approve the attach prompt.
• the Gateway or node host can spawn npx chrome-devtools-mcp@latest --autoConnect

• This path is higher-risk than the isolated fluffbuzz profile because it can act inside your signed-in browser session.
• FluffBuzz does not launch the browser for this driver; it only attaches.
• FluffBuzz uses the official Chrome DevTools MCP --autoConnect flow here. If userDataDir is set, it is passed through to target that user data directory.
• Existing-session can attach on the selected host or through a connected browser node. If Chrome lives elsewhere and no browser node is connected, use remote CDP or a node host instead.

​

Isolation guarantees

• Dedicated user data dir: never touches your personal browser profile.
• Dedicated ports: avoids 9222 to prevent collisions with dev workflows.
• Deterministic tab control: target tabs by targetId, not “last tab”.

​

Browser selection

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: checks /Applications and ~/Applications.
• Linux: looks for google-chrome, brave, microsoft-edge, chromium, etc.
• Windows: checks common install locations.

​

Control API (optional)

• Status/start/stop: GET /, POST /start, POST /stop
• Tabs: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• Actions: POST /navigate, POST /act
• Hooks: POST /hooks/file-chooser, POST /hooks/dialog
• Downloads: POST /download, POST /wait/download
• Debugging: GET /console, POST /pdf
• Debugging: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Network: POST /response/body
• State: GET /cookies, POST /cookies/set, POST /cookies/clear
• State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Settings: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-fluffbuzz-password: <gateway password> or HTTP Basic auth with that password

• This standalone loopback browser API does not consume trusted-proxy or Tailscale Serve identity headers.
• If gateway.auth.mode is none or trusted-proxy, these loopback browser routes do not inherit those identity-bearing modes; keep them loopback-only.

​

/act error contract

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): kind is missing or unrecognized.
• ACT_INVALID_REQUEST (HTTP 400): action payload failed normalization or validation.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector was used with an unsupported action kind.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (or wait --fn) is disabled by config.
• ACT_TARGET_ID_MISMATCH (HTTP 403): top-level or batched targetId conflicts with request target.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): action is not supported for existing-session profiles.

​

Playwright requirement

• ARIA snapshots
• Page screenshots for the managed fluffbuzz browser when a per-tab CDP WebSocket is available
• Page screenshots for existing-session / Chrome MCP profiles
• existing-session ref-based screenshots (--ref) from snapshot output

• navigate
• act
• AI snapshots / role snapshots
• CSS-selector element screenshots (--element)
• full browser PDF export

​

Docker Playwright install

docker compose run --rm fluffbuzz-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

How it works (internal)

​

CLI quick reference

fluffbuzz browser status
fluffbuzz browser start
fluffbuzz browser stop            # also clears emulation on attach-only/remote CDP
fluffbuzz browser tabs
fluffbuzz browser tab             # shortcut for current tab
fluffbuzz browser tab new
fluffbuzz browser tab select 2
fluffbuzz browser tab close 2
fluffbuzz browser open https://example.com
fluffbuzz browser focus abcd1234
fluffbuzz browser close abcd1234

fluffbuzz browser screenshot
fluffbuzz browser screenshot --full-page
fluffbuzz browser screenshot --ref 12        # or --ref e12
fluffbuzz browser snapshot
fluffbuzz browser snapshot --format aria --limit 200
fluffbuzz browser snapshot --interactive --compact --depth 6
fluffbuzz browser snapshot --efficient
fluffbuzz browser snapshot --labels
fluffbuzz browser snapshot --selector "#main" --interactive
fluffbuzz browser snapshot --frame "iframe#main" --interactive
fluffbuzz browser console --level error
fluffbuzz browser errors --clear
fluffbuzz browser requests --filter api --clear
fluffbuzz browser pdf
fluffbuzz browser responsebody "**/api" --max-chars 5000

fluffbuzz browser navigate https://example.com
fluffbuzz browser resize 1280 720
fluffbuzz browser click 12 --double           # or e12 for role refs
fluffbuzz browser type 23 "hello" --submit
fluffbuzz browser press Enter
fluffbuzz browser hover 44
fluffbuzz browser scrollintoview e12
fluffbuzz browser drag 10 11
fluffbuzz browser select 9 OptionA OptionB
fluffbuzz browser download e12 report.pdf
fluffbuzz browser waitfordownload report.pdf
fluffbuzz browser upload /tmp/fluffbuzz/uploads/file.pdf
fluffbuzz browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
fluffbuzz browser dialog --accept
fluffbuzz browser wait --text "Done"
fluffbuzz browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
fluffbuzz browser evaluate --fn '(el) => el.textContent' --ref 7
fluffbuzz browser highlight e12
fluffbuzz browser trace start
fluffbuzz browser trace stop

fluffbuzz browser cookies
fluffbuzz browser cookies set session abc123 --url "https://example.com"
fluffbuzz browser cookies clear
fluffbuzz browser storage local get
fluffbuzz browser storage local set theme dark
fluffbuzz browser storage session clear
fluffbuzz browser set offline on
fluffbuzz browser set headers --headers-json '{"X-Debug":"1"}'
fluffbuzz browser set credentials user pass            # --clear to remove
fluffbuzz browser set geo 37.7749 -122.4194 --origin "https://example.com"
fluffbuzz browser set media dark
fluffbuzz browser set timezone America/New_York
fluffbuzz browser set locale en-US
fluffbuzz browser set device "iPhone 14"

• upload and dialog are arming calls; run them before the click/press that triggers the chooser/dialog.
• click/type/etc require a ref from snapshot (numeric 12 or role ref e12). CSS selectors are intentionally not supported for actions.
• Download, trace, and upload paths are constrained to FluffBuzz temp roots: /tmp/fluffbuzz{,/downloads,/uploads} (fallback: ${os.tmpdir()}/fluffbuzz/...).
• upload can also set file inputs directly via --input-ref or --element.

• --format ai (default with Playwright): AI snapshot with numeric refs (aria-ref="<n>").
• --format aria: accessibility tree, no refs; inspection only.
• --efficient (or --mode efficient): compact role snapshot preset. Set browser.snapshotDefaults.mode: "efficient" to make this the default (see Gateway configuration).
• --interactive, --compact, --depth, --selector force a role snapshot with ref=e12 refs. --frame "<iframe>" scopes role snapshots to an iframe.
• --labels adds a viewport-only screenshot with overlayed ref labels (prints MEDIA:<path>).

​

Snapshots and refs

• AI snapshot (numeric refs): fluffbuzz browser snapshot (default; --format ai)
  • Output: a text snapshot that includes numeric refs.
  • Actions: fluffbuzz browser click 12, fluffbuzz browser type 23 "hello".
  • Internally, the ref is resolved via Playwright’s aria-ref.
• Role snapshot (role refs like e12): fluffbuzz browser snapshot --interactive (or --compact, --depth, --selector, --frame)
  • Output: a role-based list/tree with [ref=e12] (and optional [nth=1]).
  • Actions: fluffbuzz browser click e12, fluffbuzz browser highlight e12.
  • Internally, the ref is resolved via getByRole(...) (plus nth() for duplicates).
  • Add --labels to include a viewport screenshot with overlayed e12 labels.

• Refs are not stable across navigations; if something fails, re-run snapshot and use a fresh ref.
• If the role snapshot was taken with --frame, role refs are scoped to that iframe until the next role snapshot.

​

Wait power-ups

• Wait for URL (globs supported by Playwright):
  • fluffbuzz browser wait --url "**/dash"
• Wait for load state:
  • fluffbuzz browser wait --load networkidle
• Wait for a JS predicate:
  • fluffbuzz browser wait --fn "window.ready===true"
• Wait for a selector to become visible:
  • fluffbuzz browser wait "#main"

fluffbuzz browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Debug workflows

1. fluffbuzz browser snapshot --interactive
2. Use click <ref> / type <ref> (prefer role refs in interactive mode)
3. If it still fails: fluffbuzz browser highlight <ref> to see what Playwright is targeting
4. If the page behaves oddly:
   • fluffbuzz browser errors --clear
   • fluffbuzz browser requests --filter api --clear
5. For deep debugging: record a trace:
   • fluffbuzz browser trace start
   • reproduce the issue
   • fluffbuzz browser trace stop (prints TRACE:<path>)

​

JSON output

fluffbuzz browser status --json
fluffbuzz browser snapshot --interactive --json
fluffbuzz browser requests --filter api --json
fluffbuzz browser cookies --json

​

State and environment knobs

• Cookies: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Headers: set headers --headers-json '{"X-Debug":"1"}' (legacy set headers --json '{"X-Debug":"1"}' remains supported)
• HTTP basic auth: set credentials user pass (or --clear)
• Geolocation: set geo <lat> <lon> --origin "https://example.com" (or --clear)
• Media: set media dark|light|no-preference|none
• Timezone / locale: set timezone ..., set locale ...
• Device / viewport:
  • set device "iPhone 14" (Playwright device presets)
  • set viewport 1280 720

​

Security and privacy

• The fluffbuzz browser profile may contain logged-in sessions; treat it as sensitive.
• browser act kind=evaluate / fluffbuzz browser evaluate and wait --fn execute arbitrary JavaScript in the page context. Prompt injection can steer this. Disable it with browser.evaluateEnabled=false if you do not need it.
• For logins and anti-bot notes (X/Twitter, etc.), see Browser login + X/Twitter posting.
• Keep the Gateway/node host private (loopback or tailnet-only).
• Remote CDP endpoints are powerful; tunnel and protect them.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​

Troubleshooting

​

CDP startup failure vs navigation SSRF block

• CDP startup or readiness failure means FluffBuzz cannot confirm that the browser control plane is healthy.
• Navigation SSRF block means the browser control plane is healthy, but a page navigation target is rejected by policy.

• CDP startup or readiness failure:
  • Chrome CDP websocket for profile "fluffbuzz" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
• Navigation SSRF block:
  • open, navigate, snapshot, or tab-opening flows fail with a browser/network policy error while start and tabs still work

fluffbuzz browser --browser-profile fluffbuzz start
fluffbuzz browser --browser-profile fluffbuzz tabs
fluffbuzz browser --browser-profile fluffbuzz open https://example.com

• If start fails with not reachable after start, troubleshoot CDP readiness first.
• If start succeeds but tabs fails, the control plane is still unhealthy. Treat this as a CDP reachability problem, not a page-navigation problem.
• If start and tabs succeed but open or navigate fails, the browser control plane is up and the failure is in navigation policy or the target page.
• If start, tabs, and open all succeed, the basic managed-browser control path is healthy.

• Browser config defaults to a fail-closed SSRF policy object even when you do not configure browser.ssrfPolicy.
• For the local loopback fluffbuzz managed profile, CDP health checks intentionally skip browser SSRF reachability enforcement for FluffBuzz’s own local control plane.
• Navigation protection is separate. A successful start or tabs result does not mean a later open or navigate target is allowed.

• Do not relax browser SSRF policy by default.
• Prefer narrow host exceptions such as hostnameAllowlist or allowedHostnames over broad private-network access.
• Use dangerouslyAllowPrivateNetwork: true only in intentionally trusted environments where private-network browser access is required and reviewed.

​

Agent tools + how control works

• browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

• browser snapshot returns a stable UI tree (AI or ARIA).
• browser act uses the snapshot ref IDs to click/type/drag/select.
• browser screenshot captures pixels (full page or element).
• browser accepts:
  • profile to choose a named browser profile (fluffbuzz, chrome, or remote CDP).
  • target (sandbox | host | node) to select where the browser lives.
  • In sandboxed sessions, target: "host" requires agents.defaults.sandbox.browser.allowHostControl=true.
  • If target is omitted: sandboxed sessions default to sandbox, non-sandbox sessions default to host.
  • If a browser-capable node is connected, the tool may auto-route to it unless you pin target="host" or target="node".

​

Related

• Tools Overview — all available agent tools
• Sandboxing — browser control in sandboxed environments
• Security — browser control risks and hardening