peerd: A Browser-Native AI Agent Harness

peerd is a browser-native AI agent harness that allows users to run a full agent loop directly within their browser. By utilizing the browser as its runtime and security model, peerd can drive browser tabs, execute code in sandboxed environments, and share builds peer-to-peer, all while maintaining a strict "no backend, no telemetry" architecture.

Core Architecture and Design

peerd is organized into five top-level modules, each handling a specific part of the agent's lifecycle:

  • peerd-provider (p): Manages model adapters for providers like Anthropic, OpenRouter, and Ollama.
  • peerd-egress (e): Acts as the security chokepoint, managing the encrypted vault for API keys, the audit log, and outbound HTTP request filtering via safeFetch and webFetch.
  • peerd-engine (e): Hosts the sandboxes for execution, including WebVMs, Notebooks, and Apps.
  • peerd-runtime (r): The core agent loop, managing tools, memory, skills, and the overall goal-seeking behavior.
  • peerd-distributed (d): A peer-to-peer network layer for agent-to-agent communication (available in the preview channel).

Sandboxed Execution Environments

To ensure safety and performance, peerd provides four distinct types of execution instances, choosing the lightest weight option based on the task:

WebVM

WebVM uses CheerpX to emulate a sandboxed Debian Linux environment in WebAssembly. It provides a full POSIX shell and its own disk (via IDB overlay), making it suitable for tasks requiring real binaries or multi-language stacks. All HTTP egress from the VM is intercepted and routed through peerd-egress for security.

Notebooks and Headless Workers

Notebooks are sealed Web Workers with their own JS realm and an OPFS file tree. They boot in hundreds of milliseconds and are used for JS-based compute. A "headless worker" is an ephemeral version of the Notebook, running offscreen for the agent's own quick computations without a visible tab.

Apps

Apps are HTML documents built by the agent and rendered in sandboxed iframes with opaque origins. This ensures that the agent-created applications remain isolated from the extension's internal state and the user's browser session.

Security Model and Trust Boundaries

peerd's security is based on the browser platform's hardened boundaries rather than custom cryptography. The system is designed so that the agent holding API keys never interacts with raw page bytes or runs untrusted code directly.

Actor Trusted With Constraint
The Vault API keys and secrets Decrypted only via Touch ID/passkey; keys never leave the device except to the provider.
The Main Agent Conversation and planning Never reads raw page bytes or runs untrusted code directly.
The Disposable Runner Driving and reading pages No access to keys or its own network; output is fenced as untrusted.
The Egress Chokepoint Every outbound byte Enforces provider allowlists and SSRF guards; bare fetch is forbidden.
The Sandboxes Running code Isolated via V8 isolates and opaque-origin iframes.

Technical Implementation Details

peerd is built using vanilla JavaScript (ES2024+) with no build step, no bundler, and no TypeScript (using JSDoc and // @ts-check for type safety). All third-party runtime dependencies, such as Mithril.js for the UI and Moonshine for speech-to-text, are vendored and SHA-verified to comply with the browser's Manifest V3 Content Security Policy (CSP).

Community Discussion and Insights

While the project has received praise for its technical ambition, some users have raised questions regarding its security and the potential for prompt injection. One user questioned the efficacy of the "untrusted" fencing of summaries, asking:

If the web runners return summarized results and those are still treated as untrusted, what's stopping a summary itself from carrying the injection up to the main loop?

In response to these architectural choices, the author noted that a new model is being developed where a "resident" agent owns every tab. This would further isolate contexts and ensure that the orchestrator does not have low-level tab interactions available to it, reducing the attack surface for prompt injections.

Sources

Related

  • Project
    NotASithLord/peerd

    A web-native AI agent runtime that runs directly in the browser to interact with tabs and web apps while maintaining strict security boundaries.

  • Project
    vercel-labs/coding-agent-template

    A Vercel‑hosted template that lets authenticated users create AI‑driven coding tasks (Claude, Codex, Copilot, Cursor, Gemini, opencode). It spins up a Vercel Sandbox, runs the chosen agent, commits changes to an AI‑generated branch, and shows live logs. Built with Next.js 15, Tailwind, Neon Postgres, and Vercel AI Gateway; supports multi‑user OAuth, per‑user API keys, and optional sandbox keep‑alive for iterative work.

  • Project
    herdrdev/herdr

    A persistent background runtime for coding agents that ensures sessions remain active across restarts and network drops while providing a socket API for agent coordination.

  • Project
    jo-inc/camofox-browser

    camofox-browser is a Node.js server that runs a patched Firefox (Camoufox) with built‑in anti‑bot fingerprint spoofing and exposes a REST API for AI agents. It returns compact accessibility snapshots, stable element references, cookie import, proxy/GeoIP handling, VNC login, and optional Playwright tracing, all deployable via Docker, Fly.io, Railway, or locally.

  • Project
    shepherd-agents/shepherd

    A runtime substrate for AI agents that records execution traces and uses OS-level sandboxing to ensure agent outputs are reviewed and approved before being applied to the workspace.