# 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 running instance
./browser.sh restart [ARGS...]# stop + build + start, forwards ARGS
./browser.sh status           # check if running + MCP responsive
./browser.sh log              # tail last 50 lines of browser log
```

## 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)
- 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).
