Profiles (multi-browser)

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

• apus-managed: a dedicated Chromium-based browser instance with its own user data directory + CDP port
• remote: an explicit CDP URL (Chromium-based browser running elsewhere)
• existing session: your existing Chrome profile via Chrome DevTools MCP auto-connect

Defaults:

• The apus profile is auto-created if missing.
• The user profile is built-in for Chrome MCP existing-session attach.
• Existing-session profiles are opt-in beyond user; create them with --driver existing-session.
• Local CDP ports allocate from 18800-18899 by default.
• Deleting a profile moves its local data directory to Trash.

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

Existing session via Chrome DevTools MCP

Apus can also attach to a running Chromium-based browser profile through the official Chrome DevTools MCP server. This reuses the tabs and login state already open in that browser profile.

Official background and setup references:

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

Built-in profile: user. Create your own custom existing-session profile if you want a different name or browser data directory.

By default the built-in user profile uses Chrome MCP auto-connect, which targets the default local Google Chrome profile. Use userDataDir for Brave, Edge, Chromium, or a non-default Chrome profile. ~ expands to your OS home directory:

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
    },
  },
}

Then in the matching browser:

1. Open that browser's inspect page for remote debugging.
2. Enable remote debugging.
3. Keep the browser running and approve the connection prompt when Apus attaches.

Common inspect pages:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

Live attach smoke test:

apus browser --browser-profile user start
apus browser --browser-profile user status
apus browser --browser-profile user tabs
apus browser --browser-profile user snapshot --format ai

What success looks like:

• status shows driver: existing-session
• status shows transport: chrome-mcp
• status shows running: true
• tabs lists your already-open browser tabs
• snapshot returns refs from the selected live tab

What to check if attach does not work:

• the target Chromium-based browser is version 144+
• remote debugging is enabled in that browser's inspect page
• the browser showed and you accepted the attach consent prompt
• if Chrome was started with an explicit --remote-debugging-port, set browser.profiles.<name>.cdpUrl to that DevTools endpoint instead of relying on Chrome MCP auto-connect
• apus doctor migrates old extension-based browser config and checks that Chrome is installed locally for default auto-connect profiles, but it cannot enable browser-side remote debugging for you

For startup failures, check the browser/chrome-mcp logs for a bounded, redacted tail of subprocess stderr when available.

Agent use:

• Use profile="user" when you need the user's logged-in browser state.
• If you use a custom existing-session profile, pass that explicit profile name.
• Only choose this mode when the user is at the computer to approve the attach prompt.
• The Gateway or node host starts the packaged Chrome DevTools MCP server on its own runtime, Node or Bun.

Notes:

• This path is higher-risk than the isolated apus profile because it can act inside your signed-in browser session.
• Apus does not launch the browser for this driver; it only attaches.
• Stopping or failing an attach closes the owned MCP subprocess and its verified descendants, not the already-running browser. Replacement attaches wait for cleanup; if cleanup cannot be verified, Apus reports an error instead of treating the session as closed.
• Apus uses the official Chrome DevTools MCP --autoConnect flow here. If userDataDir is set, it is passed through to target that user data directory.
• Existing-session can attach on the selected host or through a connected browser node. If Chrome lives elsewhere and no browser node is connected, use remote CDP or a node host instead.
• Chrome MCP targets and snapshot refs are scoped to one MCP subprocess. After that process restarts, run browser tabs again, explicitly select a fresh target before target-specific work, and take a new snapshot before using refs. Each ref is valid only for its target and latest snapshot. Old aliases are not transferred to a replacement tab, even when its URL matches.
• Starting a snapshot refresh invalidates that tab's earlier refs, even if the refresh fails. Condition waits reuse the current document snapshot and preserve its refs. A stale-document error retires only that tab's snapshot; a later poll captures the replacement document. Take a fresh snapshot after navigation before performing another ref-based action.
• Labeled screenshots can include controls in multiple frames. Successful captures remove their temporary labels from each frame before returning.
• Chrome DevTools MCP currently routes page tools by a process-local numeric page ID. Process-scoped handles prevent reuse across subprocess replacement, but an in-process browser-context replacement between adjacent tool calls can still retarget an action. Fully atomic routing requires upstream page-tool support for stable target IDs.

Custom Chrome MCP launch

Apus includes an exact-pinned Chrome DevTools MCP 1.10.1 dependency with a temporary document-identity patch and starts its CLI directly with the runtime running Apus, Node or Bun. The npm package carries the patched dependency; source checkouts obtain it through pnpm install. This keeps the server used at runtime aligned with Apus's browser contract tests. The patch is tracked in the upstream repair.

Override the server per profile for a custom executable or version. Custom servers are operator-managed and must preserve Chrome MCP's connection arguments and document-bound element identity.

mcpArgs extends the selected server's arguments. Existing configurations that set mcpCommand: "npx" continue to select the built-in pinned server. The default launcher enables --experimentalVision for native coordinate clicks. A custom mcpCommand must expose the click_at tool to support click-coords; pass the server's corresponding feature flag in mcpArgs when required.

When mcpArgs does not set a connection option, Apus forwards a configured cdpUrl to Chrome MCP instead of generating --autoConnect:

• http(s)://... → --browserUrl <url> (DevTools HTTP discovery endpoint).
• ws(s)://... → --wsEndpoint <url> (direct CDP WebSocket).

Explicit endpoint arguments in mcpArgs override cdpUrl; adding --autoConnect alongside an endpoint does not hide it. Apus uses the selected endpoint for CDP control and checks Browser CDP policy before starting Chrome MCP. A matching blockedHostnames entry denies attachment even when private-network access is trusted. Unrelated blocklist entries do not prevent attachment, and the default strict-policy restrictions still apply.

Invalid, empty, duplicate, or conflicting endpoint arguments fail with an error before launch. Supply one valid endpoint, or omit cdpUrl and endpoint arguments to use host-local attachment.

When an endpoint is selected, userDataDir is ignored: Chrome MCP attaches to the running browser behind that endpoint rather than opening a profile directory.