coderClaw

Browser (coderclaw-managed)

CoderClaw can run a dedicated Chrome/Brave/Edge/Chromium profile that the agent controls. It is isolated from your personal browser and is managed through a small local control service inside the Gateway (loopback only).

Beginner view:

What you get

This browser is not your daily driver. It is a safe, isolated surface for agent automation and verification.

Quick start

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

If you get “Browser disabled”, enable it in config (see below) and restart the Gateway.

Profiles: coderclaw vs chrome

Set browser.defaultProfile: "coderclaw" if you want managed mode by default.

Configuration

Browser settings live in ~/.coderclaw/coderclaw.json.

{
  browser: {
    enabled: true, // default: true
    // 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: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      coderclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Notes:

Use Brave (or another Chromium-based browser)

If your system default browser is Chromium-based (Chrome/Brave/Edge/etc), CoderClaw uses it automatically. Set browser.executablePath to override auto-detection:

CLI example:

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

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

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

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

Local vs remote control

Remote CDP URLs can include auth:

CoderClaw preserves the auth when calling /json/* endpoints and when connecting to the CDP WebSocket. Prefer environment variables or secrets managers for tokens instead of committing them to config files.

Node browser proxy (zero-config default)

If you run a node host on the machine that has your browser, CoderClaw can auto-route browser tool calls to that node without any extra browser config. This is the default path for remote gateways.

Notes:

Browserless (hosted remote CDP)

Browserless is a hosted Chromium service that exposes CDP endpoints over HTTPS. You can point a CoderClaw browser profile at a Browserless region endpoint and authenticate with your API key.

Example:

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

Notes:

Security

Key ideas:

Remote CDP tips:

Profiles (multi-browser)

CoderClaw supports multiple named profiles (routing configs). Profiles can be:

Defaults:

All control endpoints accept ?profile=<name>; the CLI uses --browser-profile.

Chrome extension relay (use your existing Chrome)

CoderClaw can also drive your existing Chrome tabs (no separate “coderclaw” Chrome instance) via a local CDP relay + a Chrome extension.

Full guide: Chrome extension

Flow:

If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.

Sandboxed sessions

If the agent session is sandboxed, the browser tool may default to target="sandbox" (sandbox browser). Chrome extension relay takeover requires host browser control, so either:

Setup

  1. Load the extension (dev/unpacked):
coderclaw browser extension install
  1. Use it:

Optional: if you want a different name or relay port, create your own profile:

coderclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

Notes:

Isolation guarantees

Browser selection

When launching locally, CoderClaw picks the first available:

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

You can override with browser.executablePath.

Platforms:

Control API (optional)

For local integrations only, the Gateway exposes a small loopback HTTP API:

All endpoints accept ?profile=<name>.

If gateway auth is configured, browser HTTP routes require auth too:

Playwright requirement

Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require Playwright. If Playwright isn’t installed, those endpoints return a clear 501 error. ARIA snapshots and basic screenshots still work for coderclaw-managed Chrome. For the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright.

If you see Playwright is not available in this gateway build, install the full Playwright package (not playwright-core) and restart the gateway, or reinstall CoderClaw with browser support.

Docker Playwright install

If your Gateway runs in Docker, avoid npx playwright (npm override conflicts). Use the bundled CLI instead:

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

To persist browser downloads, set PLAYWRIGHT_BROWSERS_PATH (for example, /home/node/.cache/ms-playwright) and make sure /home/node is persisted via CODERCLAW_HOME_VOLUME or a bind mount. See Docker.

How it works (internal)

High-level flow:

This design keeps the agent on a stable, deterministic interface while letting you swap local/remote browsers and profiles.

CLI quick reference

All commands accept --browser-profile <name> to target a specific profile. All commands also accept --json for machine-readable output (stable payloads).

Basics:

Inspection:

Actions:

State:

Notes:

Snapshots and refs

CoderClaw supports two “snapshot” styles:

Ref behavior:

Wait power-ups

You can wait on more than just time/text:

These can be combined:

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

Debug workflows

When an action fails (e.g. “not visible”, “strict mode violation”, “covered”):

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

JSON output

--json is for scripting and structured tooling.

Examples:

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

Role snapshots in JSON include refs plus a small stats block (lines/chars/refs/interactive) so tools can reason about payload size and density.

State and environment knobs

These are useful for “make the site behave like X” workflows:

Security & privacy

Troubleshooting

For Linux-specific issues (especially snap Chromium), see Browser troubleshooting.

Agent tools + how control works

The agent gets one tool for browser automation:

How it maps:

This keeps the agent deterministic and avoids brittle selectors.

This site is open source. Improve this page.