# sovereign_browser — Agent Rules

## Browser Management (CRITICAL)

**ALWAYS use `./browser.sh` to start/stop/restart the browser.** Never run `./sovereign_browser` directly — it will hang the terminal because the GUI process keeps stdout/stderr open, which blocks the command runner.

```bash
./browser.sh start [ARGS...]  # build + launch (detached, waits for MCP ready), forwards ARGS
./browser.sh stop             # kill ALL running instances
./browser.sh restart [ARGS...]# stop + build + start, forwards ARGS
./browser.sh status           # list all running instances + MCP status
./browser.sh log              # tail the browser log
./browser.sh mcp-url          # print MCP endpoint URL(s) for running instance(s)
```

**Multiple instances:** if the default MCP port (17777) is already in use by another instance, the browser automatically falls back to an OS-assigned port and records it in `/tmp/sovereign_browser_<pid>.port`. `browser.sh` reads these discovery files to find/stop/status every instance. Use `./browser.sh mcp-url` to discover the actual endpoint(s).

## Login

The browser requires Nostr login before browser tools work. The simplest way is to pass `--login-method` on the command line — this bypasses the GTK login dialog entirely, no MCP call needed:

```bash
# Generate a fresh key and log in immediately — no credentials needed
./browser.sh start --login-method generate

# Generate a key and open a URL in one command
./browser.sh start --login-method generate --url https://example.com

# Log in with a local key (nsec)
./browser.sh start --login-method local --nsec nsec1...

# Read-only mode (npub, no signing)
./browser.sh start --login-method readonly --npub npub1...
```

Other login methods: `seed` (BIP-39 mnemonic), `nip46` (bunker:// URL), `nsigner` (hardware signer). Run `./sovereign_browser --help` for the full flag list.

Alternatively, you can still log in at runtime via the MCP `login` tool with `{"method": "generate"}` (or `local`, `seed`, `readonly`, `nip46`, `nsigner`).

## MCP Server

- Endpoint: `http://localhost:17777/mcp` (Streamable HTTP) for the first instance; subsequent instances get an OS-assigned port — use `./browser.sh mcp-url` to discover the actual endpoint(s)
- 100 tools available (login, navigation, snapshot, interaction, tabs, cookies, screenshots, etc.)
- See `.roo/agents.md` for the full tool list and workflow

## Building

```bash
make          # build
make clean    # clean
```

WebKitGTK + C99. Links `webkit2gtk-4.1`, `libsoup-3.0`, `nostr_core_lib` (vendored).
