Local vs remote control

Stopping behavior differs by profile mode:

Remote CDP URLs can include auth:

Apus 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, Apus can auto-route browser tool calls to that node when the Gateway host has no local browser capability. Automatic routing prefers the host, including a stopped managed browser whose executable is installed. Explicit target="node", a node selector, or gateway.nodes.browser.node overrides that preference; target="host" always stays on the host.

The selected host profile owns existing-session, extension, attach-only, and remote-CDP connections even when no managed-browser executable is installed. Launch failures, invalid executable settings, permission errors, and page-action failures stay on that owner; Apus does not replay them on another machine. Automatic host fallback from a selected node is allowed only before the selected node handles a request. Once an action reaches the node, its follow-up snapshot or settings stay on that node instead of switching browsers.

Standalone runs such as apus agent exec use the host browser when no Gateway or node route is selected. They do not need Gateway credentials for local browser control. Sandbox routing and host-control restrictions still apply. To discover browser nodes through a local Gateway from a standalone run, set gateway.nodes.browser.mode="auto"; discovery runs only when local capability is unavailable. An explicit node target or pin, remote Gateway configuration, or APUS_GATEWAY_URL also keeps node discovery enabled. Explicit node targets and pins retain connection and authentication errors.

Notes:

Browserless (hosted remote CDP)

Browserless is a hosted Chromium service that exposes CDP connection URLs over HTTPS and WebSocket. Apus can use either form, but for a remote browser profile the simplest option is the direct WebSocket URL from Browserless' connection docs.

Example:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
      },
    },
  },
}

Notes:

Browserless Docker on the same host

When Browserless is self-hosted in Docker and Apus runs on the host, treat Browserless as an externally managed CDP service:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
      },
    },
  },
}

The address in browser.profiles.browserless.cdpUrl must be reachable from the Apus process. Browserless must also advertise a matching reachable endpoint; set Browserless EXTERNAL to that same public-to-Apus WebSocket base, such as ws://127.0.0.1:3000, ws://browserless:3000, or a stable private Docker network address. If /json/version returns webSocketDebuggerUrl pointing at an address Apus cannot reach, CDP HTTP can look healthy while the WebSocket attach still fails.

Do not leave attachOnly unset for a loopback Browserless profile. Without attachOnly, Apus treats the loopback port as a local managed browser profile and may report that the port is in use but not owned by Apus.

Direct WebSocket CDP providers

Some hosted browser services expose a direct WebSocket endpoint rather than the standard HTTP-based CDP discovery (/json/version). Apus accepts three CDP URL shapes and picks the right connection strategy automatically:

apus browser doctor uses the same discovery-first, WebSocket-fallback logic as runtime attach, so a bare-root URL that connects successfully is not reported as unreachable by diagnostics.

Browserbase

Browserbase is a cloud platform for running headless browsers with built-in CAPTCHA solving, stealth mode, and residential proxies.

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
      },
    },
  },
}

Notes:

Notte

Notte is a cloud platform for running headless browsers with built-in stealth, residential proxies, and a CDP-native WebSocket gateway.

{
  browser: {
    enabled: true,
    defaultProfile: "notte",
    profiles: {
      notte: {
        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",
      },
    },
  },
}

Notes: