Chrome Integration

When to use Chrome integration

Choose Chrome integration when:

• The task needs authenticated access: the agent must work in sites where you are already logged in (email, internal tools, banking, SaaS dashboards).
• The task depends on your profile: specific cookies, local storage data, or extensions in your Chrome profile are required.
• Watching locally matters: Chrome opens a visible window on your machine (unless headless mode is enabled), alongside the in-app browser panel.

For tasks without those needs, the built-in browser is simpler and does not require Chrome to be installed.

How it works

When Chrome integration is selected and an agent opens the browser, Gamut:

1. Detects your local Chrome installation at standard paths on macOS, Windows, and Linux.
2. Copies your selected profile's session data (cookies, login data, local storage, session storage) into a dedicated working directory on first launch. Subsequent launches reuse this copy, so the agent accumulates its own session state without affecting your real Chrome profile.
3. Launches Chrome with remote debugging enabled, connecting via the Chrome DevTools Protocol (CDP). On macOS, Chrome launches in the background so it does not steal focus from your current application.
4. Streams the browser to the Gamut UI for the same panel view and interaction as the built-in browser.

The browser tools (browser_open, browser_click, browser_fill, and so on) are identical across browser hosts. Switching from the built-in browser to Chrome requires no changes to an agent's instructions.

Selecting a Chrome profile

Chrome supports multiple user profiles, and Gamut can use any of them. When Chrome is detected, the settings page shows a profile selector populated from your Chrome installation's Local State file.

1. Open Settings > Browser.
2. Set Browser Host to Google Chrome.
3. In the Chrome Profile dropdown, choose the profile agents should use. Each entry shows the display name and associated email address (if signed in).
4. Select None for a fresh profile with no pre-existing session data.

After the initial copy, the agent maintains its own working profile directory:

• New cookies and storage entries stay isolated from your real Chrome profile.
• Password changes or logouts in your real profile do not propagate to the copy. Log in again through the agent's browser session, or delete the agent's browser data to trigger a fresh copy.

Headless mode

By default, Chrome integration opens a visible window. Enable Headless Mode in the browser settings to run Chrome without one (for example, to keep it from stealing focus while the agent browses).

With headless mode enabled:

• Chrome runs invisibly in the background.
• The browser panel in the Gamut UI still shows the live preview.
• A realistic user-agent string is set automatically to reduce detection by websites that block headless browsers.
• The viewport is set to 1920x1080 for consistent rendering.

Platform support

If Chrome is not found at any of these paths, the Chrome option appears disabled in the settings with the message "Chrome not found on this system".

Downloads

Files downloaded through Chrome integration are saved to a dedicated downloads directory for the agent, separate from your personal Downloads folder.

Limitations and security considerations

• Sensitive data exposure: selecting a Chrome profile gives the agent access to that profile's cookies and login sessions. Only select profiles whose sessions you are comfortable sharing with the agent.
• One browser per agent: each agent instance gets its own Chrome process and working directory, so multiple agents can use Chrome simultaneously without sharing state.
• External close detection: manually closing the Chrome window that Gamut launched notifies both the UI (the browser panel disappears) and the agent's container (so it can clean up its internal state).
• Stale lock files: after a Chrome crash, Gamut cleans up lock files (SingletonLock, SingletonSocket, SingletonCookie) on the next launch so the browser can start cleanly.