Firefox Agent Bridge

A small Firefox extension that exposes an allowlisted WebExtension API to local scripts and agents.

This is not a bookmark sync engine. Firefox already has browser.bookmarks. The extension is a bridge: while Firefox is open, a script on the same machine can call those functions over http://127.0.0.1:17634.

Agents: start at AGENTS.md.

Why this exists

Firefox will not let an outside process talk to Places. Editing places.sqlite while the browser is running loses deletes. The supported path is browser.bookmarks inside an extension, plus native messaging so a localhost HTTP host can reach that extension.

Pieces

Piece	Role
extension/	WebExtension (bookmarks + nativeMessaging)
host/	Native host: stdio to Firefox, HTTP to scripts
tools/client.py	Signed Python caller (FAB_KEY_FILE)
examples/replace_named_folder.py	Sample "replace this folder" script

Install (this workstation)

1. Register the native host (once):

   powershell -NoProfile -File tools\install-native-host.ps1
   

   That registers HKCU\Software\Mozilla\NativeMessagingHosts\com.easygoingaming.firefox_agent_bridge.

   Then create a client key outside that state directory and give the file to tooling:

   python tools\register_client.py add --name cursor-agent --write-key $HOME\.fab\cursor-agent.json
   $env:FAB_KEY_FILE = "$HOME\.fab\cursor-agent.json"
   

2. Load the extension. Firefox Release will not keep an unsigned add-on across restarts:

   • about:debugging#/runtime/this-firefox
   • Load Temporary Add-on
   • pick extension\manifest.json

   Permanent install: Mozilla-signed .xpi — docs/signing.md. Start with --channel=unlisted.

3. Leave Firefox open. The extension starts the host; GET http://127.0.0.1:17634/health should return JSON.

Call it

$env:FAB_KEY_FILE = "$HOME\.fab\cursor-agent.json"
python tools/client.py meta.methods
python tools/client.py bookmarks.search "[{\"title\":\"10.132.x.x\"}]"

See AGENTS.md for the method list, HTTP surface, and failure modes.

Security

• Binds 127.0.0.1 only. Browser Origin headers are rejected; Host must be loopback.
• Calls (except /health) must be signed by a registered Ed25519 client. The host keeps public keys only.
• Only the methods in extension/background.js ALLOWED run. No history, cookies, tabs, or onMessageExternal in v0.1.
• Another add-on with bookmarks already has Places; this bridge does not give it a new path in.

License

MIT.