Setup Guide

ClawChrome gives an AI agent a separate official Google Chrome session that can be started, controlled, observed, streamed, idled, resumed, and persisted around the workflow. Use this guide to get from a clean setup to a connected agent control path with a persistent browser session.

• Google Chrome Stable installed on the machine that will run the browser session.
• A ClawChrome install or account path from your team, the public docs, or the agent-readable setup resource.
• An MCP-capable client such as an agent harness, IDE agent, or local MCP runner.
• Permission to automate the websites and accounts involved in your workflow.

Think of ClawChrome as a browser runtime rather than a test-script wrapper. The agent gets a lightweight isolated Chrome session instead of taking over a user’s live browser or attaching to a shared browser farm.

The main pieces are:

• Official Google Chrome runs as the browser baseline, not a Chromium fork.
• Each workflow can use a separate isolated session so account state, cookies, and browser context stay scoped.
• Agents can control the browser through MCP-native actions or direct API control, depending on the integration.
• The normal driving path stays outside CDP and WebDriver through ClawChrome’s custom OS browser control.
• Teams can view the browser session through direct low-latency streaming when a run needs inspection.
• Sessions can persist for logged-in workflows or idle/resume when the deployment supports it.

Use this model when deciding how to structure agent work. A short task can start a fresh session. A recurring authenticated workflow should use a dedicated persistent session. A production workflow that needs human review should keep session viewing enabled so the team can inspect what the agent is doing.

Use the install path provided for your environment, then verify that the clawchrome command is available:

clawchrome --help

If you are setting up from an agent, point it at the agent-readable resource:

1
read https://clawchrome.com/skill.md

For a local developer setup, confirm the host can launch Chrome and that the browser profile location is writable by the user running ClawChrome.

Start ClawChrome with the MCP server enabled:

clawchrome start --mcp

For a workflow that should open a starting URL immediately, use the URL form supported by your installed version:

clawchrome start --url https://example.com

Keep the terminal running while your MCP client is connected. If Chrome does not appear, check that Google Chrome Stable is installed, the display is available, and no stale browser process is holding the profile lock.

Add ClawChrome to your MCP client using the command or endpoint printed by clawchrome start --mcp. The exact UI depends on the client, but the connection should expose browser tools for actions and observation.

After connecting, ask the client to list tools and confirm ClawChrome actions are present before sending a production workflow.

For platform integrations, use the direct product API path when your orchestration system needs to create sessions, inspect status, stream the browser, or coordinate multiple agent runs programmatically.

Most workflows can be built from five browser actions:

A typical agent loop is:

1
navigate to the target page
2
observe the page state
3
click or type to complete the next step
4
observe again
5
extract the result

Prefer observation and extraction over screenshot-only reasoning when the workflow can be completed from structured page state. Use visual inspection when the page layout, captcha, or target element requires it.

Persistent sessions let agents continue workflows that require login state. Use a dedicated browser profile for each sensitive workflow, and avoid sharing one profile across unrelated sites or customers.

Recommended practice:

• Create separate sessions for separate customers, accounts, or environments.
• Treat cookies and browser profiles as sensitive credentials.
• Revoke or rotate session access when a task is complete.
• Document which agent or workflow owns each persistent session.

If a site signs the browser out unexpectedly, restart the session, confirm the profile path is the same, and check whether the site invalidated the login state.

Confirm Google Chrome Stable is installed and available on the host. If you are running headless infrastructure, verify that the display and window manager expected by your deployment are running.

Restart clawchrome start --mcp, copy the current connection details into the MCP client, and ask the client to list tools again. Some clients require a full reload after changing MCP configuration.

Make sure the Chrome window is focused and visible to the ClawChrome session. Use observe before acting so the agent can target the current page state instead of stale assumptions.

Use a normal Chrome profile, keep session state consistent, and reduce unnecessary retries. For high-friction sites, collect the target URL, account state, challenge behavior, and agent steps before contacting support.

• Read the FAQ for common browser runtime and session questions.
• Review ClawChrome vs. Browserbase when comparing hosted browser sessions.
• Contact the team from Contact when a production workflow needs deployment or blocked-site review.