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	Stdlib Python caller
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 writes %LOCALAPPDATA%\firefox-agent-bridge\token and HKCU\Software\Mozilla\NativeMessagingHosts\com.easygoingaming.firefox_agent_bridge.

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

$token = Get-Content $env:LOCALAPPDATA\firefox-agent-bridge\token -Raw
curl.exe -s -H "Authorization: Bearer $token" http://127.0.0.1:17634/v1/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.
• Every mutating call (and most reads) needs Authorization: Bearer <token>.
• 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. Same-user processes that steal the token do — that is the agent contract.

License

MIT.