Chrome Integration

Chrome integration lets your agents use your local Google Chrome browser instead of the built-in headless browser. This means agents can access websites where you are already logged in, using your existing cookies, saved passwords, and session data -- without needing to re-authenticate.

When to Use Chrome Integration

Choose Chrome integration when:

• You need authenticated access. The agent needs to interact with a site where you are already logged in (email, internal tools, banking, SaaS dashboards), and you do not want to re-enter credentials.
• You want to use your existing browser profile. Your Chrome profile has specific cookies, local storage data, or extensions that the task requires.
• You need to watch in real time. Chrome opens a visible browser window on your machine (unless headless mode is enabled), so you can see exactly what the agent is doing alongside the in-app browser panel.

If the task does not require authenticated sessions or existing profile data, 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, Superagent:

1. Detects your local Chrome installation. Superagent looks for Chrome in standard installation 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 the first time it launches. Subsequent launches reuse this copy so the agent can accumulate 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 is launched in the background so it does not steal focus from your current application.
4. Streams the browser to the Superagent UI so you can watch and interact through the browser panel, exactly as with the built-in browser.

The agent uses the same set of browser tools (browser_open, browser_click, browser_fill, and so on) regardless of which browser host is selected. Switching from the built-in browser to Chrome does not require any changes to your agent's instructions.

Selecting a Chrome Profile

Chrome supports multiple user profiles, and Superagent 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.

To select a profile:

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

Profile data is copied on first launch for each agent. After the initial copy, the agent maintains its own working profile directory. This means:

• Changes the agent makes (new cookies, storage entries) are isolated from your real Chrome profile.
• If you update your Chrome password or log out of a site, the agent's copy is not automatically updated. You may need to 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 browser window on your machine. If you prefer Chrome to run without a visible window (for example, to prevent it from stealing focus while the agent browses), enable Headless Mode in the browser settings.

With headless mode enabled:

• Chrome runs invisibly in the background.
• The browser panel in the Superagent 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

Chrome integration works on all three platforms:

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

Downloads

When using Chrome integration, files downloaded by the browser are saved to a dedicated downloads directory for the agent, separate from your personal Downloads folder. This keeps agent-downloaded files organized and prevents them from mixing with your own downloads.

Limitations and Security Considerations

• Profile data is copied, not shared. The agent works with a copy of your profile data. It cannot see changes you make to your real Chrome profile after the initial copy, and your real profile is not affected by the agent's activity.
• Sensitive data exposure. When you select a Chrome profile, the agent gains 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. Multiple agents can use Chrome simultaneously, each with their own isolated instance.
• External close detection. If you manually close the Chrome window that Superagent launched, the system detects this and notifies both the UI (the browser panel disappears) and the agent's container (so it can clean up its internal state).
• Stale lock files. If Chrome crashes, Superagent automatically cleans up lock files (SingletonLock, SingletonSocket, SingletonCookie) on the next launch so the browser can start cleanly.