AgentBridge — Let any AI agent work on your Mac, safely

One terminal command connects your Mac to any cloud AI agent. The agent can build, read files, and run commands on your Mac — and every risky action needs your approval first.

Quickstart · How it stays safe · SECURITY.md · Issues

What it is

Your Mac, remote-controlled by an AI agent — without handing over the keys.

AgentBridge runs a small, secure server on your Mac. Point your cloud agent (Claude, ChatGPT, Cursor, Instinct, HappyCapy, or your own) at it, and the agent can do real work on your machine: run Xcode builds, read and write files, execute commands — all inside strict limits you control.

• One command to install — no Homebrew, no npm install, zero dependencies beyond Node (which the installer sets up for you)

• You approve the risky stuff — commands outside a strict allowlist and all deletions wait for your yes on the Mac itself, bound to the exact argv and the SHA-256 of every workspace file named in it

• Files stay in a jail — the agent only sees the folder you choose, never your whole disk. Writes are versioned and deletes go to a trash folder, so mistakes are recoverable

• Every action is logged — a tamper-evident audit trail of who did what, when

• Works with any agent — speaks MCP-style JSON-RPC (initialize, tools/list, tools/call). If your agent can call tools, it can use AgentBridge

Related MCP server: macos-sys-assist

Install in one command

curl -fsSL https://github.com/ndpvt-web/agent-bridge/releases/latest/download/install-agent-bridge.sh | bash

Then pair your agent:

agent-bridge pair

This prints a tunnel URL and a one-time pairing code (valid 10 minutes). Paste both into your cloud agent. Done — the bridge now runs 24/7 in the background via launchd.

Prefer to build from source? bash scripts/build-installer.sh builds the installer locally. npm test builds the installer first, then runs every suite.

Two permission modes

Pick at install (the installer asks, or pass --mode limited|full); switch anytime:

agent-bridge mode full      # v1-style: full control. Loud warning, asks to confirm.
agent-bridge mode limited   # back to the hardened default

• LIMITED (default, recommended) — the hardened mode this README describes: filesystem jail, command allowlist, and your on-device approval for anything risky.

• FULL — the old v1 behavior: no jail, no allowlist, no approvals, shell access on. Any paired agent can run anything as you. Choose it only if you trust every paired agent completely; the bridge prints a loud warning every time it starts in FULL mode, and every switch is written to the audit log.

Both modes keep Ed25519-signed requests, per-agent keys you can revoke, and the tamper-evident audit log.

What your agent can do

• Read, write, and list files inside your chosen folder

• Run approved commands — builds, tests, and a curated set of safe dev tools without asking

• Work while you're away — the bridge stays up, you stay in control

• Get its own identity — each agent pairs with its own Ed25519 key, so you can see and revoke each one separately

How it stays safe

1. Signed requests — every call is Ed25519-signed by a paired agent key. No key, no access. Captured requests can't be replayed.

2. Strict command allowlist — per-program argument rules, not patterns an agent can talk its way around.

3. Filesystem jail — realpath-checked; symlink escapes and writes through links are refused.

4. Human approval gate — anything outside the allowlist pings your Mac for a yes/no. The approval binds the exact argv plus the SHA-256 of every workspace file named in it (which must exist when you approve), and re-checks those hashes before anything runs. One honest limit: interpreters and build tools read files beyond the argv (imports, Makefiles) that can't be enumerated — the approval line warns you when that's the case.

5. Tamper-evident audit log — hash-chained; edits to history show up as tampering.

The installer's downloads are version-pinned and SHA-256-verified against hashes embedded in the script, fail-closed on mismatch. Full details in SECURITY.md and the threat model.

Day-to-day

For agent developers

AgentBridge speaks MCP-style JSON-RPC over the tunnel. Call initialize, list tools with tools/list, and invoke them with tools/call. See the docs for the tool catalogue and pairing handshake.

License

MIT