fengming 0.3.9 → 0.3.11

package/docs/tools/browser-control.md

@@ -1,391 +0,0 @@
----
-summary: "FengMing browser control API, CLI reference, and scripting actions"
-read_when:
-  - Scripting or debugging the agent browser via the local control API
-  - Looking for the `fengming 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 `fengming 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 FengMing does not launch those browser processes.
-
-If shared-secret gateway auth is configured, browser HTTP routes require auth too:
-
-- `Authorization: Bearer <gateway token>`
-- `x-fengming-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 `fengming` 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
-FengMing, 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
-FENGMING_INSTALL_BROWSER=1 ./scripts/docker/setup.sh
-```
-
-For an existing image, install through the bundled CLI instead:
-
-```bash
-docker compose run --rm fengming-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
-`FENGMING_HOME_VOLUME` or a bind mount. FengMing 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
-fengming browser status
-fengming browser start
-fengming browser start --headless # one-shot local managed headless launch
-fengming browser stop            # also clears emulation on attach-only/remote CDP
-fengming browser tabs
-fengming browser tab             # shortcut for current tab
-fengming browser tab new
-fengming browser tab select 2
-fengming browser tab close 2
-fengming browser open https://example.com
-fengming browser focus abcd1234
-fengming browser close abcd1234
-```
-
-</Accordion>
-
-<Accordion title="Inspection: screenshot, snapshot, console, errors, requests">
-
-```bash
-fengming browser screenshot
-fengming browser screenshot --full-page
-fengming browser screenshot --ref 12        # or --ref e12
-fengming browser screenshot --labels
-fengming browser snapshot
-fengming browser snapshot --format aria --limit 200
-fengming browser snapshot --interactive --compact --depth 6
-fengming browser snapshot --efficient
-fengming browser snapshot --labels
-fengming browser snapshot --urls
-fengming browser snapshot --selector "#main" --interactive
-fengming browser snapshot --frame "iframe#main" --interactive
-fengming browser console --level error
-fengming browser errors --clear
-fengming browser requests --filter api --clear
-fengming browser pdf
-fengming browser responsebody "**/api" --max-chars 5000
-```
-
-</Accordion>
-
-<Accordion title="Actions: navigate, click, type, drag, wait, evaluate">
-
-```bash
-fengming browser navigate https://example.com
-fengming browser resize 1280 720
-fengming browser click 12 --double           # or e12 for role refs
-fengming browser click-coords 120 340        # viewport coordinates
-fengming browser type 23 "hello" --submit
-fengming browser press Enter
-fengming browser hover 44
-fengming browser scrollintoview e12
-fengming browser drag 10 11
-fengming browser select 9 OptionA OptionB
-fengming browser download e12 report.pdf
-fengming browser waitfordownload report.pdf
-fengming browser upload /tmp/fengming/uploads/file.pdf
-fengming browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
-fengming browser dialog --accept
-fengming browser dialog --dismiss --dialog-id d1
-fengming browser wait --text "Done"
-fengming browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
-fengming browser evaluate --fn '(el) => el.textContent' --ref 7
-fengming browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
-fengming browser highlight e12
-fengming browser trace start
-fengming browser trace stop
-```
-
-</Accordion>
-
-<Accordion title="State: cookies, storage, offline, headers, geo, device">
-
-```bash
-fengming browser cookies
-fengming browser cookies set session abc123 --url "https://example.com"
-fengming browser cookies clear
-fengming browser storage local get
-fengming browser storage local set theme dark
-fengming browser storage session clear
-fengming browser set offline on
-fengming browser set headers --headers-json '{"X-Debug":"1"}'
-fengming browser set credentials user pass            # --clear to remove
-fengming browser set geo 37.7749 -122.4194 --origin "https://example.com"
-fengming browser set media dark
-fengming browser set timezone America/New_York
-fengming browser set locale en-US
-fengming 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 FengMing 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 FengMing temp roots: `/tmp/fengming{,/downloads,/uploads}` (fallback: `${os.tmpdir()}/fengming/...`).
-- `upload` can also set file inputs directly via `--input-ref` or `--element`.
-
-Stable tab ids and labels survive Chromium raw-target replacement when FengMing
-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, FengMing 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
-
-FengMing supports two "snapshot" styles:
-
-- **AI snapshot (numeric refs)**: `fengming browser snapshot` (default; `--format ai`)
-  - Output: a text snapshot that includes numeric refs.
-  - Actions: `fengming browser click 12`, `fengming browser type 23 "hello"`.
-  - Internally, the ref is resolved via Playwright's `aria-ref`.
-
-- **Role snapshot (role refs like `e12`)**: `fengming browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`)
-  - Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).
-  - Actions: `fengming browser click e12`, `fengming 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`)**: `fengming browser snapshot --format aria`
-  - Output: the accessibility tree as structured nodes.
-  - Actions: `fengming 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):
-  - `fengming browser wait --url "**/dash"`
-- Wait for load state:
-  - `fengming browser wait --load networkidle`
-- Wait for a JS predicate:
-  - `fengming browser wait --fn "window.ready===true"`
-- Wait for a selector to become visible:
-  - `fengming browser wait "#main"`
-
-These can be combined:
-
-```bash
-fengming 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. `fengming browser snapshot --interactive`
-2. Use `click <ref>` / `type <ref>` (prefer role refs in interactive mode)
-3. If it still fails: `fengming browser highlight <ref>` to see what Playwright is targeting
-4. If the page behaves oddly:
-   - `fengming browser errors --clear`
-   - `fengming browser requests --filter api --clear`
-5. For deep debugging: record a trace:
-   - `fengming browser trace start`
-   - reproduce the issue
-   - `fengming browser trace stop` (prints `TRACE:<path>`)
-
-## JSON output
-
-`--json` is for scripting and structured tooling.
-
-Examples:
-
-```bash
-fengming browser status --json
-fengming browser snapshot --interactive --json
-fengming browser requests --filter api --json
-fengming 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 fengming browser profile may contain logged-in sessions; treat it as sensitive.
-- `browser act kind=evaluate` / `fengming 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 `fengming 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

@@ -1,173 +0,0 @@
----
-summary: "Fix Chrome/Brave/Edge/Chromium CDP startup issues for FengMing 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"
-
-FengMing'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 \"fengming\"."}
-```
-
-### Root cause
-
-On Ubuntu (and many Linux distros), the default Chromium installation is a **snap package**. Snap's AppArmor confinement interferes with how FengMing 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. FengMing
-  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 `FENGMING_BROWSER_HEADLESS=0`,
-  `browser.headless: false`, or `browser.profiles.<name>.headless: false`,
-  remove that headed override, set `FENGMING_BROWSER_HEADLESS=1`, start `Xvfb`,
-  run `fengming browser start --headless` for a one-shot managed launch, or run
-  FengMing 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 FengMing config (`~/.fengming/fengming.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 FengMing 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/.fengming/browser/fengming/user-data \
-  about:blank &
-```
-
-3. Optionally create a systemd user service to auto-start Chrome:
-
-```ini
-# ~/.config/systemd/user/fengming-browser.service
-[Unit]
-Description=FengMing Browser (Chrome CDP)
-After=network.target
-
-[Service]
-ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.fengming/browser/fengming/user-data about:blank
-Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=default.target
-```
-
-Enable with: `systemctl --user enable --now fengming-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`                                                     |
-| `FENGMING_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
-`fengming 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. FengMing can see local Chrome,
-but there are no open tabs available to attach to.
-
-Fix options:
-
-1. **Use the managed browser:** `fengming browser start --browser-profile fengming`
-   (or set `browser.defaultProfile: "fengming"`).
-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 `fengming` 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

@@ -1,77 +0,0 @@
----
-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 fengming 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?
-
-FengMing controls a **dedicated Chrome profile** (named `fengming`, orange-tinted UI). This is separate from your daily browser profile.
-
-For agent browser tool calls:
-
-- Default choice: the agent should use its isolated `fengming` 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
-fengming browser start
-fengming browser open https://x.com
-```
-
-If you have multiple profiles, pass `--browser-profile <name>` (the default is `fengming`).
-
-## 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
-fengming browser open https://x.com --browser-profile fengming
-```
-
-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)