GitHub - NotASithLord/peerd: The first AI agent harness native to the browser. A Chrome/Firefox extension that runs the agent loop in your browser — drives your tabs, spins up sandboxed compute (JS notebooks, WASM Linux VMs, client-side apps), and shares what it builds peer-to-peer. BYOK · no backend · no telemetry.

peerd is the first AI agent harness native to the browser. It's a Chrome/Firefox extension that runs a full agent loop inside the browser you already use — with the tabs and sessions you already have. It reads and drives your pages, spins up sandboxed compute (JS Notebooks, full Linux VMs compiled to WebAssembly, personal client-side apps), and — on the preview channel — shares what it builds over a peer-to-peer WebRTC network built for agent-to-agent communication. BYOK to the model provider of your choice. No backend, no telemetry, no cloud component in the data path.

newdemo.mp4

The bet is structural: peerd uses the browser as its runtime, its hypervisor, and its security model. It inherits decades of hardened browser platform work — V8 isolates for sandboxing, WebCrypto for the vault, WebAuthn passkeys to unlock it, opaque-origin iframes, Subresource Integrity — and writes zero lines of its own cryptographic or process-isolation code. The agent that holds your keys never reads a raw page; a disposable runner with no keys and no network does, and its output comes back fenced as untrusted. And the agent never takes its own word for success: every action it drives is verified against the live page before it counts as done — the model proposes, the browser decides. (More at peerd.ai.) The name is always lowercase: peerd. Status: 0.x — experimental beta. It works and the initial feature buildout is complete and integrated (see STATUS.md), but the surface is still moving: breaking changes are likely, storage formats may shift, and it drives your browser and holds your API keys — use it with care. There is no "V1" commitment; versions stay in the 0.x range until the surface stabilizes. For the full, itemized list of what's shipped — categorized by module — see FEATURES.md. Install Developer preview: Load the source tree unpacked using the steps below. This is the current source-of-truth install path for contributors and early testers. Store packages: Chrome Web Store / Firefox Add-ons listings will be linked here once they are approved.

Store packages omit preview-only dweb pieces and the preview/dev advanced automation path. Dweb preview (research package): GitHub Releases may include signed preview artifacts. If there is no release attached yet, use the source install path below. The preview package includes the decentralized web (dweb) layer — peer-to-peer dwapps between peerd instances. It's intended for contributors and early testers — the dweb protocol is research-grade and subject to change. Most users want one of the two store packages above. The preview installs alongside the store package as a separate extension ("peerd preview") with its own isolated storage; move state between them explicitly via Settings → Export & import. Preview package install paths (Firefox is the smoother of the two):

Firefox: click peerd-preview-firefox.xpi on the release page — it's AMO-signed, installs like any extension, and auto-updates. Chrome on macOS / Windows (recommended): load the zip unpacked. Chrome hard-disables off-store CRX installs on these platforms ("may have been added without your knowledge", enable toggle locked) — and field testing showed even an ExtensionInstallAllowlist policy visible in chrome://policy does NOT unlock it on an unmanaged machine (Chrome wants MDM-grade management). So don't fight it: download peerd-preview-chrome.zip, unzip it, enable Developer mode at chrome://extensions, Load unpacked, and pick the unzipped folder. Caveats: no auto-update (download the new zip per release) and the extension ID is machine-specific, not the table's CRX ID. This is a Chrome platform restriction on all self-hosted extensions, not a peerd choice. Chrome on Linux (or any policy-managed Chrome): download peerd-preview-chrome.crx, enable Developer mode at chrome://extensions, and drag the file onto the page.

Auto-update then follows the feed at peerd.ai/updates/.

Extension IDs (verify which package you're running):

package id

peerd (Chrome store) verify from the store listing or chrome://extensions after install

peerd (Firefox store) peerd@peerd.ai

peerd preview (Chrome) lpdkhfeldihoejbbfonnbekpjclkknoc (CRX installs only — an unpacked load gets a machine-specific ID)

peerd preview (Firefox) peerd-preview@peerd.ai

Getting started peerd has no build step — you load the extension/ folder straight into Chrome as it is on disk. You need a Chromium-based browser (Chrome, Edge, Brave, Arc, …) and a model to talk to: a key from Anthropic and/or OpenRouter, or a local Ollama (keyless, no bill, nothing leaves your machine). BYOK: any key lives encrypted in a local vault and is only ever sent to that provider. 1. Get the code git clone https://github.com/NotASithLord/peerd.git cd peerd

2. Load the extension in Chrome

Open chrome://extensions. Turn on Developer mode (toggle, top-right). Click Load unpacked. Select the extension/ folder inside the repo — not the repo root. (The folder with manifest.json in it.)

peerd now appears in your extensions list. Click the puzzle-piece icon in the toolbar and pin peerd so its icon is always visible. 3. Open peerd and set up the vault Click the peerd toolbar icon — the side panel opens. On first run you create a local vault: unlock with Touch ID / a passkey (recommended) or a recovery passphrase. Keys, chat history, and the audit log are all encrypted on this device; nothing leaves your machine except the calls to your model provider. 4. Add your API key(s) Open Settings (gear icon) → API keys. Paste a key for Anthropic (sk-ant-…) and/or OpenRouter (sk-or-…). You can set both at once — each is stored independently. Choose a default under Default model for new chats, and switch the model per chat from the picker above the message box.

5. Chat Back in the chat, type a message. peerd can read and drive your open tabs, run shell commands in a sandboxed in-browser Linux VM, build small apps, search the web, and more. Turn on Confirm before actions in Settings if you want to approve each tab/automation step first (off by default). Updating after a code change. Hit the reload icon on the peerd card in chrome://extensions. The side panel, offscreen document, and any open VM/JS/App tabs reload with it. Firefox (temporary). about:debugging#/runtime/this-firefox → Load Temporary Add-on → pick extension/manifest.json. Re-load on each edit. Firefox parity is still being polished — Chrome is the primary target for now. Generated files. extension/manifest.json and extension/shared/channel-config.js are GENERATED (the checked-in copies are the dev defaults — preview channel, dweb on). Don't hand-edit them; change manifests/*.json or packaging/default-settings.mjs and run bun run gen:dev. CI fails if they drift. Why the permissions? peerd asks for broad host access (<all_urls>, and debugger on the preview/dev channels) because driving arbitrary tabs and reading the page the agent is acting on is the whole point. Each permission, why it's needed, and what the store build strips is spelled out in docs/store/PERMISSION-JUSTIFICATIONS.md — and the trust boundaries (BYOK vault, egress allowlist, untrusted-content handling, no telemetry) in SECURITY.md. Project conventions (the short version)

Plain vanilla JS, ES2024+. No TypeScript, no JSX, no bundler, no npm inside extension/. ES modules only. Strict mode by default. Pure functions and reducers over classes. Classes only where lifecycle is real (vault, VM, ports). safeFetch / webFetch for all outbound HTTP — bare fetch is forbidden. Comments explain why, not what. The codebase is security-sensitive and is meant to be read carefully.

The full version of these conventions and the architectural rationale lives in CLAUDE.md (orientation), ARCHITECTURE.md (module organization), and DESIGN.md (the full technical design record — vault crypto, dispatcher gates, prompt-injection defenses, the MV3 keepalive trick; long, historical, and worth searching before reopening a settled question). The five modules The five-letter wordmark is the architecture — each colored letter is one top-level module. Each module has its own README with how it works today, its public API, known limitations, and TODOs:

Module Role

p · cyan peerd-provider Model adapters — Anthropic, OpenRouter, Ollama (streaming, caching, cost, retries)

e · red peerd-egress Security — the vault, the egress chokepoint, the denylist, the audit log

e · amber peerd-engine Sandboxes — WebVMs, Notebooks, Apps, and the headless worker

r · green peerd-runtime The agent — loop, tools, do/get/check, memory, skills, review, goal mode, voice

d · magenta peerd-distributed The dweb — the peer-to-peer network (preview channel only)

The brand IS the architecture: cross-module imports go through each module's index.js, never deep paths; nothing outside peerd-distributed/ imports it at all. See ARCHITECTURE.md for the dependency graph. Trust boundaries peerd's safety is who is allowed to do what — small, legible boundaries enforced by the browser platform, not by peerd's own crypto. Two principles run through all of it: the agent that holds your keys never touches a raw page or runs untrusted code, and the agent never gets the final word on correctness — every action is verified against the live page before it counts as done.

Actor Trusted with Never

The vault (peerd-egress/vault) your API keys + secrets, decrypted only after Touch ID / passkey / passphrase unlock; idle auto-lock leaving the device — keys go only to the provider you chose

The main agent (peerd-runtime/loop) the conversation, planning, tool dispatch reading raw page bytes or running untrusted code directly

The disposable runner (peerd-runtime/runner) driving + reading the page via do/get/check holding keys or its own network; its output returns wrapUntrusted-fenced

The egress chokepoint (safeFetch / webFetch) every outbound byte — provider allowlist + denylist + SSRF guard being bypassed; a bare fetch is lint-forbidden

The sandboxes (WebVM · Notebook · App) running code — V8 isolates + opaque-origin iframes extension access; their HTTP routes back through egress

Web content nothing by default being trusted — all of it is fenced as untrusted input

The shape is proposes vs. decides: the AI proposes and drives; the browser platform (WebCrypto vault, WebAuthn unlock, V8 isolates, SRI) and the live DOM are what actually decide. Full detail in SECURITY.md and DESIGN.md. Documentation Read CLAUDE.md for quick orientation, ARCHITECTURE.md for the five-module organization, ARCHITECTURE-CHANGES.md if you're picking up work from a previous session, FEATURES.md for what's shipped, PACKAGING.md for the dual-distribution packaging system, and docs/DECISIONS.md for the recorded design tradeoffs. Repo layout The five-letter wordmark is the architecture (see ARCHITECTURE.md).