Isolation guarantees

• Dedicated user data dir: never touches your personal browser profile.
• Dedicated ports: avoids 9222 to prevent collisions with dev workflows.
• Deterministic tab control: tabs returns suggestedTargetId first, then stable tabId handles such as t1, optional labels, and the raw targetId. Agents should reuse suggestedTargetId; raw ids remain available for debugging and compatibility. Profiles configured with driver: "extension" can also return a runtime-scoped numeric webExtensionTabId for Chrome WebExtensions API calls. It is omitted for other drivers and must not replace suggestedTargetId or tabId in Apus browser actions.

Browser selection

When launching locally, Apus picks the first available:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

You can override with browser.executablePath.

Platforms:

• macOS: checks /Applications and ~/Applications.
• Linux: checks common Chrome/Brave/Edge/Chromium locations under /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium, and /usr/lib/chromium-browser, plus Playwright-managed Chromium under PLAYWRIGHT_BROWSERS_PATH or $XDG_CACHE_HOME/ms-playwright (defaults to ~/.cache/ms-playwright when XDG_CACHE_HOME is unset or empty). Cache paths use Playwright's environment precedence, including npm configuration aliases; relative paths resolve from INIT_CWD or the current working directory. PLAYWRIGHT_BROWSERS_PATH=0 selects the installed Playwright package's .local-browsers directory.
• Windows: checks common install locations.

Control API (optional)

For scripting and debugging, the Gateway exposes a small loopback-only HTTP control API plus a matching apus browser CLI (snapshots, refs, wait power-ups, JSON output, debug workflows). See Browser control API for the full reference.