`fluffbuzz browser`

Manage FluffBuzz’s browser control surface and run browser actions (lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging). Related:

Browser tool + API: Browser tool

Common flags

--url <gatewayWsUrl>: Gateway WebSocket URL (defaults to config).
--token <token>: Gateway token (if required).
--timeout <ms>: request timeout (ms).
--expect-final: wait for a final Gateway response.
--browser-profile <name>: choose a browser profile (default from config).
--json: machine-readable output (where supported).

Quick start (local)

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

Quick troubleshooting

If start fails with not reachable after start, troubleshoot CDP readiness first. If start and tabs succeed but open or navigate fails, the browser control plane is healthy and the failure is usually navigation SSRF policy. Minimal sequence:

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

Detailed guidance: Browser troubleshooting

Lifecycle

fluffbuzz browser status
fluffbuzz browser start
fluffbuzz browser stop
fluffbuzz browser --browser-profile fluffbuzz reset-profile

Notes:

For attachOnly and remote CDP profiles, fluffbuzz browser stop closes the active control session and clears temporary emulation overrides even when FluffBuzz did not launch the browser process itself.
For local managed profiles, fluffbuzz browser stop stops the spawned browser process.

If the command is missing

If fluffbuzz browser is an unknown command, check plugins.allow in ~/.fluffbuzz/fluffbuzz.json. When plugins.allow is present, the bundled browser plugin must be listed explicitly:

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

browser.enabled=true does not restore the CLI subcommand when the plugin allowlist excludes browser. Related: Browser tool

Profiles

Profiles are named browser routing configs. In practice:

fluffbuzz: launches or attaches to a dedicated FluffBuzz-managed Chrome instance (isolated user data dir).
user: controls your existing signed-in Chrome session via Chrome DevTools MCP.
custom CDP profiles: point at a local or remote CDP endpoint.

fluffbuzz browser profiles
fluffbuzz browser create-profile --name work --color "#FF5A36"
fluffbuzz browser create-profile --name chrome-live --driver existing-session
fluffbuzz browser create-profile --name remote --cdp-url https://browser-host.example.com
fluffbuzz browser delete-profile --name work

Use a specific profile:

fluffbuzz browser --browser-profile work tabs

Tabs

fluffbuzz browser tabs
fluffbuzz browser tab new
fluffbuzz browser tab select 2
fluffbuzz browser tab close 2
fluffbuzz browser open https://docs.fluffbuzz.com
fluffbuzz browser focus <targetId>
fluffbuzz browser close <targetId>

Snapshot / screenshot / actions

Snapshot:

fluffbuzz browser snapshot

Screenshot:

fluffbuzz browser screenshot
fluffbuzz browser screenshot --full-page
fluffbuzz browser screenshot --ref e12

Notes:

--full-page is for page captures only; it cannot be combined with --ref or --element.
existing-session / user profiles support page screenshots and --ref screenshots from snapshot output, but not CSS --element screenshots.

Navigate/click/type (ref-based UI automation):

fluffbuzz browser navigate https://example.com
fluffbuzz browser click <ref>
fluffbuzz browser type <ref> "hello"
fluffbuzz browser press Enter
fluffbuzz browser hover <ref>
fluffbuzz browser scrollintoview <ref>
fluffbuzz browser drag <startRef> <endRef>
fluffbuzz browser select <ref> OptionA OptionB
fluffbuzz browser fill --fields '[{"ref":"1","value":"Ada"}]'
fluffbuzz browser wait --text "Done"
fluffbuzz browser evaluate --fn '(el) => el.textContent' --ref <ref>

File + dialog helpers:

fluffbuzz browser upload /tmp/fluffbuzz/uploads/file.pdf --ref <ref>
fluffbuzz browser waitfordownload
fluffbuzz browser download <ref> report.pdf
fluffbuzz browser dialog --accept

State and storage

Viewport + emulation:

fluffbuzz browser resize 1280 720
fluffbuzz browser set viewport 1280 720
fluffbuzz browser set offline on
fluffbuzz browser set media dark
fluffbuzz browser set timezone Europe/London
fluffbuzz browser set locale en-GB
fluffbuzz browser set geo 51.5074 -0.1278 --accuracy 25
fluffbuzz browser set device "iPhone 14"
fluffbuzz browser set headers '{"x-test":"1"}'
fluffbuzz browser set credentials myuser mypass

Cookies + storage:

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 token abc123
fluffbuzz browser storage session clear

Debugging

fluffbuzz browser console --level error
fluffbuzz browser pdf
fluffbuzz browser responsebody "**/api"
fluffbuzz browser highlight <ref>
fluffbuzz browser errors --clear
fluffbuzz browser requests --filter api
fluffbuzz browser trace start
fluffbuzz browser trace stop --out trace.zip

Existing Chrome via MCP

Use the built-in user profile, or create your own existing-session profile:

fluffbuzz browser --browser-profile user tabs
fluffbuzz browser create-profile --name chrome-live --driver existing-session
fluffbuzz browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
fluffbuzz browser --browser-profile chrome-live tabs

This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead. Current existing-session limits:

snapshot-driven actions use refs, not CSS selectors
click is left-click only
type does not support slowly=true
press does not support delayMs
hover, scrollintoview, drag, select, fill, and evaluate reject per-call timeout overrides
select supports one value only
wait --load networkidle is not supported
file uploads require --ref / --input-ref, do not support CSS --element, and currently support one file at a time
dialog hooks do not support --timeout
screenshots support page captures and --ref, but not CSS --element
responsebody, download interception, PDF export, and batch actions still require a managed browser or raw CDP profile

Remote browser control (node host proxy)

If the Gateway runs on a different machine than the browser, run a node host on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required). Use gateway.nodes.browser.mode to control auto-routing and gateway.nodes.browser.node to pin a specific node if multiple are connected. Security + remote setup: Browser tool, Remote access, Tailscale, Security

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

Browser

`fluffbuzz browser`

Common flags

Quick start (local)

Quick troubleshooting

Lifecycle

If the command is missing

Profiles

Tabs

Snapshot / screenshot / actions

State and storage

Debugging

Existing Chrome via MCP

Remote browser control (node host proxy)

​fluffbuzz browser

​Common flags

​Quick start (local)

​Quick troubleshooting

​Lifecycle

​If the command is missing

​Profiles

​Tabs

​Snapshot / screenshot / actions

​State and storage

​Debugging

​Existing Chrome via MCP

​Remote browser control (node host proxy)

`fluffbuzz browser`

Common flags

Quick start (local)

Quick troubleshooting

Lifecycle

If the command is missing

Profiles

Tabs

Snapshot / screenshot / actions

State and storage

Debugging

Existing Chrome via MCP

Remote browser control (node host proxy)