AgentVeil

A privacy-first browser built for AI agents.

AgentVeil gives an AI agent everything it needs to work on the web — search, page fetching, interactive browsing, screenshots, and end-to-end encrypted agent-to-agent messaging — exposed as an MCP server that Claude Code and other MCP clients can use directly. A command-line tool (agentveil) is included as well.

Its core design rule: all traffic leaves through one local proxy tunnel you choose (Tor, or your own SOCKS5 proxy); if the tunnel is unavailable, requests are refused rather than sent directly.

MIT licensed · Windows 10/11 x64 · Python 3.11+

Why a dedicated browser for agents?

Agents browse differently from people: they read untrusted pages at machine speed, follow links they did not choose, and can be manipulated by text hidden in a page. AgentVeil is built around that:

Limits

• Privacy from websites and the network is not privacy from your model provider: a cloud LLM sees the agent's prompts and what it reads.

• Disable your agent's built-in web tools (they do not go through AgentVeil). For Claude Code: { "permissions": { "deny": ["WebFetch", "WebSearch"] } } in .claude/settings.json.

• Messaging has no forward secrecy; rotate identities for long-lived secrets.

• JavaScript widens the attack surface; use javascript=false for untrusted sites and keep Playwright updated.

• web_fetch has a Python TLS fingerprint; some sites (e.g. Wikipedia) reject it — use browser_open instead.

• AgentVeil never solves CAPTCHAs; it switches engines or suggests new_identity.

• Only AgentVeil's own traffic is covered, not the rest of the system.

• You are responsible for complying with the laws that apply to you.

Related MCP server: Wraith MCP Server

Architecture

 Agent (Claude Code / any MCP client)
        │ MCP (stdio)
        ▼
 ┌──────────────────────────── AgentVeil ────────────────────────────┐
 │ web_search / web_fetch ──┐                                        │
 │ browser_* (hardened FF) ─┼─► EgressPolicy                         │
 │ msg_* (E2E messaging) ───┘   · http(s) only, HTTPS enforced       │
 │                              · no loopback / LAN / metadata       │
 │                              · tunnel down → refuse (fail-closed) │
 │ Firefox ─► isolation shim (local SOCKS: TCP CONNECT only,         │
 │            per-connection policy check, per-identity credentials) │
 └───────────────────────────────┬───────────────────────────────────┘
                                 │ SOCKS5 (hostnames resolved remotely)
                                 ▼
                 Local tunnel: Tor  /  sing-box / Xray  /  both chained

Quick start (Windows)

See INSTALL.md for the full guide, including the offline installer.

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

Start a tunnel — either:

• Tor (no server needed):

  .venv\Scripts\agentveil.exe tor-config --bundle C:\tor --bridges none
  C:\tor\tor\tor.exe -f $HOME\.agentveil\torrc

• Your own SOCKS5 proxy (sing-box, Xray, …): set kind = "socks", port = <port>, control_port = 0 in agentveil.toml. Templates: tunnels/.

Self-test:

.venv\Scripts\agentveil.exe status --deep

Connect your agent: the installer writes .mcp.json in the project folder (Claude Code picks it up), or:

claude mcp add agentveil -- "C:\AgentVeil\.venv\Scripts\python.exe" -m agentveil -c "C:\AgentVeil\agentveil.toml" mcp

Tools

CLI equivalents: agentveil search …, agentveil fetch URL, agentveil open URL --screenshot a.png, agentveil new-identity, agentveil msg ….

Agent-to-agent messaging

1. Run a relay: agentveil relay --port 8787 (in-memory, no logs, sender-blind).

2. Optionally publish it as a Tor onion service (HiddenServiceDir / HiddenServicePort 80 127.0.0.1:8787 in torrc).

3. Set relay_url in agentveil.toml on both sides.

4. Exchange contact cards from msg_whoami (avc1.…), add them with msg_add_contact, and compare fingerprints over another channel.

5. msg_send / msg_receive. Incoming messages are labelled verified/unknown and always presented as untrusted data.

Set AGENTVEIL_PASSPHRASE before first use to store the identity key encrypted (Argon2id + XSalsa20-Poly1305).

Optional OS-level kill switch

scripts/firewall-killswitch.ps1 adds Windows Firewall rules that block AgentVeil's Python interpreter, Playwright's Firefox and its driver from reaching any non-loopback address — only the tunnel client (a separate program) can go online. Run from an elevated PowerShell; -Remove undoes it. The rule applies to the base Python interpreter used by the venv, so other programs on that interpreter (including pip) are affected too.

Tests

.venv\Scripts\python.exe -m pytest -q

The suite uses a recording SOCKS5 proxy and hostnames that exist only in that proxy (site.test) to prove that:

• hostnames always reach the tunnel unresolved (the local resolver cannot resolve site.test);

• with the tunnel down, zero requests reach the target and Firefox is never started;

• Firefox contacts nothing but the requested site — no telemetry, update or safe-browsing traffic;

• Firefox and its driver hold no non-loopback TCP sockets at the OS level;

• WebRTC is absent, WebGL is off, timezone is UTC+0, language en-US;

• tracking pixels to 127.0.0.1, redirects into private networks and environment proxy variables are all blocked/ignored;

• messages resist tampering, forgery, re-forwarding and replay; nobody else can read or drain a mailbox;

• the MCP server works end-to-end over stdio and reports clear FAIL-CLOSED / BLOCKED errors.