54 lines
2.5 KiB
Plaintext
54 lines
2.5 KiB
Plaintext
# 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).
|