nodmix 2026.5.25

package/docs/tools/browser-control.md

@@ -0,0 +1,391 @@
+---
+summary: "Nodmix browser control API, CLI reference, and scripting actions"
+read_when:
+  - Scripting or debugging the agent browser via the local control API
+  - Looking for the `nodmix browser` CLI reference
+  - Adding custom browser automation with snapshots and refs
+title: "Browser control API"
+---
+
+For setup, configuration, and troubleshooting, see [Browser](/tools/browser).
+This page is the reference for the local control HTTP API, the `nodmix browser`
+CLI, and scripting patterns (snapshots, refs, waits, debug flows).
+
+## Control API (optional)
+
+For local integrations only, the Gateway exposes a small loopback HTTP API:
+
+- Status/start/stop: `GET /`, `POST /start`, `POST /stop`
+- Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
+- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`
+- Actions: `POST /navigate`, `POST /act`
+- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`
+- Downloads: `POST /download`, `POST /wait/download`
+- Permissions: `POST /permissions/grant`
+- Debugging: `GET /console`, `POST /pdf`
+- Debugging: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
+- Network: `POST /response/body`
+- State: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`
+- State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
+- Settings: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
+
+All endpoints accept `?profile=<name>`. `POST /start?headless=true` requests a
+one-shot headless launch for local managed profiles without changing persisted
+browser config; attach-only, remote CDP, and existing-session profiles reject
+that override because Nodmix does not launch those browser processes.
+
+If shared-secret gateway auth is configured, browser HTTP routes require auth too:
+
+- `Authorization: Bearer <gateway token>`
+- `x-nodmix-password: <gateway password>` or HTTP Basic auth with that password
+
+Notes:
+
+- This standalone loopback browser API does **not** consume trusted-proxy or
+  Tailscale Serve identity headers.
+- If `gateway.auth.mode` is `none` or `trusted-proxy`, these loopback browser
+  routes do not inherit those identity-bearing modes; keep them loopback-only.
+
+### `/act` error contract
+
+`POST /act` uses a structured error response for route-level validation and
+policy failures:
+
+```json
+{ "error": "<message>", "code": "ACT_*" }
+```
+
+Current `code` values:
+
+- `ACT_KIND_REQUIRED` (HTTP 400): `kind` is missing or unrecognized.
+- `ACT_INVALID_REQUEST` (HTTP 400): action payload failed normalization or validation.
+- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` was used with an unsupported action kind.
+- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (or `wait --fn`) is disabled by config.
+- `ACT_TARGET_ID_MISMATCH` (HTTP 403): top-level or batched `targetId` conflicts with request target.
+- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): action is not supported for existing-session profiles.
+
+Other runtime failures may still return `{ "error": "<message>" }` without a
+`code` field.
+
+### Playwright requirement
+
+Some features (navigate/act/AI snapshot/role snapshot, element screenshots,
+PDF) require Playwright. If Playwright isn't installed, those endpoints return
+a clear 501 error.
+
+What still works without Playwright:
+
+- ARIA snapshots
+- Role-style accessibility snapshots (`--interactive`, `--compact`,
+  `--depth`, `--efficient`) when a per-tab CDP WebSocket is available. This is
+  a fallback for inspection and ref discovery; Playwright remains the primary
+  action engine.
+- Page screenshots for the managed `nodmix` browser when a per-tab CDP
+  WebSocket is available
+- Page screenshots for `existing-session` / Chrome MCP profiles
+- `existing-session` ref-based screenshots (`--ref`) from snapshot output
+
+What still needs Playwright:
+
+- `navigate`
+- `act`
+- AI snapshots that depend on Playwright's native AI snapshot format
+- CSS-selector element screenshots (`--element`)
+- full browser PDF export
+
+Element screenshots also reject `--full-page`; the route returns `fullPage is
+not supported for element screenshots`.
+
+If you see `Playwright is not available in this gateway build`, the packaged
+Gateway is missing the core browser runtime dependency. Reinstall or update
+Nodmix, then restart the gateway. For Docker, also install the Chromium
+browser binaries as shown below.
+
+#### Docker Playwright install
+
+If your Gateway runs in Docker, avoid `npx playwright` (npm override conflicts).
+For custom images, bake Chromium into the image:
+
+```bash
+NODMIX_INSTALL_BROWSER=1 ./scripts/docker/setup.sh
+```
+
+For an existing image, install through the bundled CLI instead:
+
+```bash
+docker compose run --rm nodmix-cli \
+  node /app/node_modules/playwright-core/cli.js install chromium
+```
+
+To persist browser downloads, set `PLAYWRIGHT_BROWSERS_PATH` (for example,
+`/home/node/.cache/ms-playwright`) and make sure `/home/node` is persisted via
+`NODMIX_HOME_VOLUME` or a bind mount. Nodmix auto-detects the persisted
+Chromium on Linux. See [Docker](/install/docker).
+
+## How it works (internal)
+
+A small loopback control server accepts HTTP requests and connects to Chromium-based browsers via CDP. Advanced actions (click/type/snapshot/PDF) go through Playwright on top of CDP; when Playwright is missing, only non-Playwright operations are available. The agent sees one stable interface while local/remote browsers and profiles swap freely underneath.
+
+## CLI quick reference
+
+All commands accept `--browser-profile <name>` to target a specific profile, and `--json` for machine-readable output.
+
+<AccordionGroup>
+
+<Accordion title="Basics: status, tabs, open/focus/close">
+
+```bash
+nodmix browser status
+nodmix browser start
+nodmix browser start --headless # one-shot local managed headless launch
+nodmix browser stop            # also clears emulation on attach-only/remote CDP
+nodmix browser tabs
+nodmix browser tab             # shortcut for current tab
+nodmix browser tab new
+nodmix browser tab select 2
+nodmix browser tab close 2
+nodmix browser open https://example.com
+nodmix browser focus abcd1234
+nodmix browser close abcd1234
+```
+
+</Accordion>
+
+<Accordion title="Inspection: screenshot, snapshot, console, errors, requests">
+
+```bash
+nodmix browser screenshot
+nodmix browser screenshot --full-page
+nodmix browser screenshot --ref 12        # or --ref e12
+nodmix browser screenshot --labels
+nodmix browser snapshot
+nodmix browser snapshot --format aria --limit 200
+nodmix browser snapshot --interactive --compact --depth 6
+nodmix browser snapshot --efficient
+nodmix browser snapshot --labels
+nodmix browser snapshot --urls
+nodmix browser snapshot --selector "#main" --interactive
+nodmix browser snapshot --frame "iframe#main" --interactive
+nodmix browser console --level error
+nodmix browser errors --clear
+nodmix browser requests --filter api --clear
+nodmix browser pdf
+nodmix browser responsebody "**/api" --max-chars 5000
+```
+
+</Accordion>
+
+<Accordion title="Actions: navigate, click, type, drag, wait, evaluate">
+
+```bash
+nodmix browser navigate https://example.com
+nodmix browser resize 1280 720
+nodmix browser click 12 --double           # or e12 for role refs
+nodmix browser click-coords 120 340        # viewport coordinates
+nodmix browser type 23 "hello" --submit
+nodmix browser press Enter
+nodmix browser hover 44
+nodmix browser scrollintoview e12
+nodmix browser drag 10 11
+nodmix browser select 9 OptionA OptionB
+nodmix browser download e12 report.pdf
+nodmix browser waitfordownload report.pdf
+nodmix browser upload /tmp/nodmix/uploads/file.pdf
+nodmix browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
+nodmix browser dialog --accept
+nodmix browser dialog --dismiss --dialog-id d1
+nodmix browser wait --text "Done"
+nodmix browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
+nodmix browser evaluate --fn '(el) => el.textContent' --ref 7
+nodmix browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
+nodmix browser highlight e12
+nodmix browser trace start
+nodmix browser trace stop
+```
+
+</Accordion>
+
+<Accordion title="State: cookies, storage, offline, headers, geo, device">
+
+```bash
+nodmix browser cookies
+nodmix browser cookies set session abc123 --url "https://example.com"
+nodmix browser cookies clear
+nodmix browser storage local get
+nodmix browser storage local set theme dark
+nodmix browser storage session clear
+nodmix browser set offline on
+nodmix browser set headers --headers-json '{"X-Debug":"1"}'
+nodmix browser set credentials user pass            # --clear to remove
+nodmix browser set geo 37.7749 -122.4194 --origin "https://example.com"
+nodmix browser set media dark
+nodmix browser set timezone America/New_York
+nodmix browser set locale en-US
+nodmix browser set device "iPhone 14"
+```
+
+</Accordion>
+
+</AccordionGroup>
+
+Notes:
+
+- `upload` and `dialog` are **arming** calls; run them before the click/press that triggers the chooser/dialog. If an action opens a modal, the action response includes `blockedByDialog` and `browserState.dialogs.pending`; pass that `dialogId` to respond directly. Dialogs handled outside Nodmix appear under `browserState.dialogs.recent`.
+- `click`/`type`/etc require a `ref` from `snapshot` (numeric `12`, role ref `e12`, or actionable ARIA ref `ax12`). CSS selectors are intentionally not supported for actions. Use `click-coords` when the visible viewport position is the only reliable target.
+- Download, trace, and upload paths are constrained to Nodmix temp roots: `/tmp/nodmix{,/downloads,/uploads}` (fallback: `${os.tmpdir()}/nodmix/...`).
+- `upload` can also set file inputs directly via `--input-ref` or `--element`.
+
+Stable tab ids and labels survive Chromium raw-target replacement when Nodmix
+can prove the replacement tab, such as same URL or a single old tab becoming a
+single new tab after form submission. Raw target ids are still volatile; prefer
+`suggestedTargetId` from `tabs` in scripts.
+
+Snapshot flags at a glance:
+
+- `--format ai` (default with Playwright): AI snapshot with numeric refs (`aria-ref="<n>"`).
+- `--format aria`: accessibility tree with `axN` refs. When Playwright is available, Nodmix binds refs with backend DOM ids to the live page so follow-up actions can use them; otherwise treat the output as inspection-only.
+- `--efficient` (or `--mode efficient`): compact role snapshot preset. Set `browser.snapshotDefaults.mode: "efficient"` to make this the default (see [Gateway configuration](/gateway/configuration-reference#browser)).
+- `--interactive`, `--compact`, `--depth`, `--selector` force a role snapshot with `ref=e12` refs. `--frame "<iframe>"` scopes role snapshots to an iframe.
+- `--labels` adds a viewport-only screenshot with overlayed ref labels (prints `MEDIA:<path>`).
+- `--urls` appends discovered link destinations to AI snapshots.
+
+## Snapshots and refs
+
+Nodmix supports two "snapshot" styles:
+
+- **AI snapshot (numeric refs)**: `nodmix browser snapshot` (default; `--format ai`)
+  - Output: a text snapshot that includes numeric refs.
+  - Actions: `nodmix browser click 12`, `nodmix browser type 23 "hello"`.
+  - Internally, the ref is resolved via Playwright's `aria-ref`.
+
+- **Role snapshot (role refs like `e12`)**: `nodmix browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`)
+  - Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).
+  - Actions: `nodmix browser click e12`, `nodmix browser highlight e12`.
+  - Internally, the ref is resolved via `getByRole(...)` (plus `nth()` for duplicates).
+  - Add `--labels` to include a viewport screenshot with overlayed `e12` labels.
+  - Add `--urls` when link text is ambiguous and the agent needs concrete
+    navigation targets.
+
+- **ARIA snapshot (ARIA refs like `ax12`)**: `nodmix browser snapshot --format aria`
+  - Output: the accessibility tree as structured nodes.
+  - Actions: `nodmix browser click ax12` works when the snapshot path can bind
+    the ref through Playwright and Chrome backend DOM ids.
+- If Playwright is unavailable, ARIA snapshots can still be useful for
+  inspection, but refs may not be actionable. Re-snapshot with `--format ai`
+  or `--interactive` when you need action refs.
+- Docker proof for the raw-CDP fallback path: `pnpm test:docker:browser-cdp-snapshot`
+  starts Chromium with CDP, runs `browser doctor --deep`, and verifies role
+  snapshots include link URLs, cursor-promoted clickables, and iframe metadata.
+
+Ref behavior:
+
+- Refs are **not stable across navigations**; if something fails, re-run `snapshot` and use a fresh ref.
+- `/act` returns the current raw `targetId` after action-triggered replacement
+  when it can prove the replacement tab. Keep using stable tab ids/labels for
+  follow-up commands.
+- If the role snapshot was taken with `--frame`, role refs are scoped to that iframe until the next role snapshot.
+- Unknown or stale `axN` refs fail fast instead of falling through to
+  Playwright's `aria-ref` selector. Run a fresh snapshot on the same tab when
+  that happens.
+
+## Wait power-ups
+
+You can wait on more than just time/text:
+
+- Wait for URL (globs supported by Playwright):
+  - `nodmix browser wait --url "**/dash"`
+- Wait for load state:
+  - `nodmix browser wait --load networkidle`
+- Wait for a JS predicate:
+  - `nodmix browser wait --fn "window.ready===true"`
+- Wait for a selector to become visible:
+  - `nodmix browser wait "#main"`
+
+These can be combined:
+
+```bash
+nodmix browser wait "#main" \
+  --url "**/dash" \
+  --load networkidle \
+  --fn "window.ready===true" \
+  --timeout-ms 15000
+```
+
+## Debug workflows
+
+When an action fails (e.g. "not visible", "strict mode violation", "covered"):
+
+1. `nodmix browser snapshot --interactive`
+2. Use `click <ref>` / `type <ref>` (prefer role refs in interactive mode)
+3. If it still fails: `nodmix browser highlight <ref>` to see what Playwright is targeting
+4. If the page behaves oddly:
+   - `nodmix browser errors --clear`
+   - `nodmix browser requests --filter api --clear`
+5. For deep debugging: record a trace:
+   - `nodmix browser trace start`
+   - reproduce the issue
+   - `nodmix browser trace stop` (prints `TRACE:<path>`)
+
+## JSON output
+
+`--json` is for scripting and structured tooling.
+
+Examples:
+
+```bash
+nodmix browser status --json
+nodmix browser snapshot --interactive --json
+nodmix browser requests --filter api --json
+nodmix browser cookies --json
+```
+
+Role snapshots in JSON include `refs` plus a small `stats` block (lines/chars/refs/interactive) so tools can reason about payload size and density.
+
+## State and environment knobs
+
+These are useful for "make the site behave like X" workflows:
+
+- Cookies: `cookies`, `cookies set`, `cookies clear`
+- Storage: `storage local|session get|set|clear`
+- Offline: `set offline on|off`
+- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (legacy `set headers --json '{"X-Debug":"1"}'` remains supported)
+- HTTP basic auth: `set credentials user pass` (or `--clear`)
+- Geolocation: `set geo <lat> <lon> --origin "https://example.com"` (or `--clear`)
+- Media: `set media dark|light|no-preference|none`
+- Timezone / locale: `set timezone ...`, `set locale ...`
+- Device / viewport:
+  - `set device "iPhone 14"` (Playwright device presets)
+  - `set viewport 1280 720`
+
+## Security and privacy
+
+- The nodmix browser profile may contain logged-in sessions; treat it as sensitive.
+- `browser act kind=evaluate` / `nodmix browser evaluate` and `wait --fn`
+  execute arbitrary JavaScript in the page context. Prompt injection can steer
+  this. Disable it with `browser.evaluateEnabled=false` if you do not need it.
+- Use `nodmix browser evaluate --timeout-ms <ms>` when the page-side function
+  may need longer than the default evaluate timeout.
+- For logins and anti-bot notes (X/Twitter, etc.), see [Browser login + X/Twitter posting](/tools/browser-login).
+- Keep the Gateway/node host private (loopback or tailnet-only).
+- Remote CDP endpoints are powerful; tunnel and protect them.
+
+Strict-mode example (block private/internal destinations by default):
+
+```json5
+{
+  browser: {
+    ssrfPolicy: {
+      dangerouslyAllowPrivateNetwork: false,
+      hostnameAllowlist: ["*.example.com", "example.com"],
+      allowedHostnames: ["localhost"], // optional exact allow
+    },
+  },
+}
+```
+
+## Related
+
+- [Browser](/tools/browser) - overview, configuration, profiles, security
+- [Browser login](/tools/browser-login) - signing in to sites
+- [Browser Linux troubleshooting](/tools/browser-linux-troubleshooting)
+- [Browser WSL2 troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

package/docs/tools/browser-linux-troubleshooting.md

@@ -0,0 +1,173 @@
+---
+summary: "Fix Chrome/Brave/Edge/Chromium CDP startup issues for Nodmix browser control on Linux"
+read_when: "Browser control fails on Linux, especially with snap Chromium"
+title: "Browser troubleshooting"
+---
+
+## Problem: "Failed to start Chrome CDP on port 18800"
+
+Nodmix's browser control server fails to launch Chrome/Brave/Edge/Chromium with the error:
+
+```
+{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"nodmix\"."}
+```
+
+### Root cause
+
+On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how Nodmix spawns and monitors the browser process.
+
+The `apt install chromium` command installs a stub package that redirects to snap:
+
+```
+Note, selecting 'chromium-browser' instead of 'chromium'
+chromium-browser is already the newest version (2:1snap1-0ubuntu2).
+```
+
+This is NOT a real browser - it's just a wrapper.
+
+Other common Linux launch failures:
+
+- `The profile appears to be in use by another Chromium process` means Chrome
+  found stale `Singleton*` lock files in the managed profile directory. Nodmix
+  removes those locks and retries once when the lock points at a dead or
+  different-host process.
+- `Missing X server or $DISPLAY` means a visible browser was explicitly
+  requested on a host without a desktop session. By default, local managed
+  profiles now fall back to headless mode on Linux when `DISPLAY` and
+  `WAYLAND_DISPLAY` are both unset. If you set `NODMIX_BROWSER_HEADLESS=0`,
+  `browser.headless: false`, or `browser.profiles.<name>.headless: false`,
+  remove that headed override, set `NODMIX_BROWSER_HEADLESS=1`, start `Xvfb`,
+  run `nodmix browser start --headless` for a one-shot managed launch, or run
+  Nodmix in a real desktop session.
+
+### Solution 1: Install Google Chrome (Recommended)
+
+Install the official Google Chrome `.deb` package, which is not sandboxed by snap:
+
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+sudo apt --fix-broken install -y  # if there are dependency errors
+```
+
+Then update your Nodmix config (`~/.nodmix/nodmix.json`):
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "executablePath": "/usr/bin/google-chrome-stable",
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+### Solution 2: Use Snap Chromium with Attach-Only Mode
+
+If you must use snap Chromium, configure Nodmix to attach to a manually-started browser:
+
+1. Update config:
+
+```json
+{
+  "browser": {
+    "enabled": true,
+    "attachOnly": true,
+    "headless": true,
+    "noSandbox": true
+  }
+}
+```
+
+2. Start Chromium manually:
+
+```bash
+chromium-browser --headless --no-sandbox --disable-gpu \
+  --remote-debugging-port=18800 \
+  --user-data-dir=$HOME/.nodmix/browser/nodmix/user-data \
+  about:blank &
+```
+
+3. Optionally create a systemd user service to auto-start Chrome:
+
+```ini
+# ~/.config/systemd/user/nodmix-browser.service
+[Unit]
+Description=Nodmix Browser (Chrome CDP)
+After=network.target
+
+[Service]
+ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.nodmix/browser/nodmix/user-data about:blank
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable with: `systemctl --user enable --now nodmix-browser.service`
+
+### Verifying the Browser Works
+
+Check status:
+
+```bash
+curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
+```
+
+Test browsing:
+
+```bash
+curl -s -X POST http://127.0.0.1:18791/start
+curl -s http://127.0.0.1:18791/tabs
+```
+
+### Config reference
+
+| Option                           | Description                                                          | Default                                                     |
+| -------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `browser.enabled`                | Enable browser control                                               | `true`                                                      |
+| `browser.executablePath`         | Path to a Chromium-based browser binary (Chrome/Brave/Edge/Chromium) | auto-detected (prefers default browser when Chromium-based) |
+| `browser.headless`               | Run without GUI                                                      | `false`                                                     |
+| `NODMIX_BROWSER_HEADLESS`      | Per-process override for local managed browser headless mode         | unset                                                       |
+| `browser.noSandbox`              | Add `--no-sandbox` flag (needed for some Linux setups)               | `false`                                                     |
+| `browser.attachOnly`             | Don't launch browser, only attach to existing                        | `false`                                                     |
+| `browser.cdpPort`                | Chrome DevTools Protocol port                                        | `18800`                                                     |
+| `browser.localLaunchTimeoutMs`   | Local managed Chrome discovery timeout                               | `15000`                                                     |
+| `browser.localCdpReadyTimeoutMs` | Local managed post-launch CDP readiness timeout                      | `8000`                                                      |
+
+On Raspberry Pi, older VPS hosts, or slow storage, raise
+`browser.localLaunchTimeoutMs` when Chrome needs more time to expose its CDP HTTP
+endpoint. Raise `browser.localCdpReadyTimeoutMs` when launch succeeds but
+`nodmix browser start` still reports `not reachable after start`. Values must
+be positive integers up to `120000` ms; invalid config values are rejected.
+
+### Problem: "No Chrome tabs found for profile=\"user\""
+
+You're using an `existing-session` / Chrome MCP profile. Nodmix can see local Chrome,
+but there are no open tabs available to attach to.
+
+Fix options:
+
+1. **Use the managed browser:** `nodmix browser start --browser-profile nodmix`
+   (or set `browser.defaultProfile: "nodmix"`).
+2. **Use Chrome MCP:** make sure local Chrome is running with at least one open tab, then retry with `--browser-profile user`.
+
+Notes:
+
+- `user` is host-only. For Linux servers, containers, or remote hosts, prefer CDP profiles.
+- `user` / other `existing-session` profiles keep the current Chrome MCP limits:
+  ref-driven actions, one-file upload hooks, no dialog timeout overrides, no
+  `wait --load networkidle`, and no `responsebody`, PDF export, download
+  interception, or batch actions.
+- Local `nodmix` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.
+- Remote CDP profiles accept `http://`, `https://`, `ws://`, and `wss://`.
+  Use HTTP(S) for `/json/version` discovery, or WS(S) when your browser
+  service gives you a direct DevTools socket URL.
+
+## Related
+
+- [Browser](/tools/browser)
+- [Browser login](/tools/browser-login)
+- [Browser WSL2 troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

package/docs/tools/browser-login.md

@@ -0,0 +1,77 @@
+---
+summary: "Manual logins for browser automation + X/Twitter posting"
+read_when:
+  - You need to log into sites for browser automation
+  - You want to post updates to X/Twitter
+title: "Browser login"
+---
+
+## Manual login (recommended)
+
+When a site requires login, **sign in manually** in the **host** browser profile (the nodmix browser).
+
+Do **not** give the model your credentials. Automated logins often trigger anti-bot defenses and can lock the account.
+
+Back to the main browser docs: [Browser](/tools/browser).
+
+## Which Chrome profile is used?
+
+Nodmix controls a **dedicated Chrome profile** (named `nodmix`, orange-tinted UI). This is separate from your daily browser profile.
+
+For agent browser tool calls:
+
+- Default choice: the agent should use its isolated `nodmix` browser.
+- Use `profile="user"` only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
+- If you have multiple user-browser profiles, specify the profile explicitly instead of guessing.
+
+Two easy ways to access it:
+
+1. **Ask the agent to open the browser** and then log in yourself.
+2. **Open it via CLI**:
+
+```bash
+nodmix browser start
+nodmix browser open https://x.com
+```
+
+If you have multiple profiles, pass `--browser-profile <name>` (the default is `nodmix`).
+
+## X/Twitter: recommended flow
+
+- **Read/search/threads:** use the **host** browser (manual login).
+- **Post updates:** use the **host** browser (manual login).
+
+## Sandboxing + host browser access
+
+Sandboxed browser sessions are **more likely** to trigger bot detection. For X/Twitter (and other strict sites), prefer the **host** browser.
+
+If the agent is sandboxed, the browser tool defaults to the sandbox. To allow host control:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Then open the host browser yourself (CLI invocations always run against the host browser):
+
+```bash
+nodmix browser open https://x.com --browser-profile nodmix
+```
+
+The agent's `browser` tool calls can then target the host once `sandbox.browser.allowHostControl: true` is set. Alternatively, disable sandboxing for the agent that posts updates.
+
+## Related
+
+- [Browser](/tools/browser)
+- [Browser Linux troubleshooting](/tools/browser-linux-troubleshooting)
+- [Browser WSL2 troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)