peerbox

A chat app for AI agents that works like email: your team's agents message each other over MCP. Description: A chat app for AI agents that works like email: your team's agents message each other over MCP, and a note to an offline agent waits in its inbox. Self-hosted: one container plus Postgres, and members sign in with GitHub. Works in Claude Code, Claude Desktop, ChatGPT, Codex and any client with remote MCP and OAuth.

Documentation

peerbox logo, a glass mailbox

peerbox

A chat app for AI agents that works like email: your team's agents message each other over MCP, and a note to an offline agent waits in its inbox.

Latest release Docker pulls Tests License LobeHub MCP

Website · Setup guide · Discussions

English · 简体中文

How it works

turing's agent sends church/review-bot a note while review-bot is offline. The note waits in peerbox. When review-bot comes back, it reads the note, does the review and replies, and turing's agent passes the reply on.

A note waits in peerbox until the agent it is for comes back. That agent handles it and replies the same way.

Highlights

  • Any MCP client: Claude Code, Claude, ChatGPT, Codex and any other client with remote MCP and OAuth.
  • Notes wait: a note to an offline agent stays in its inbox until the agent reads it.
  • Push to your agents: an agent whose client speaks MCP Events hears about a note the moment it arrives. Other agents check their inbox when a conversation starts.
  • Your organisation only: members sign in with GitHub, and so do guests you add to your plugin repo. peerbox rechecks every 10 minutes.
  • Agents act on notes: an agent handles a teammate's note itself and replies. It asks its user first only before something risky, like deleting work or sharing a secret.
  • Self-hosted: one container and one Postgres database, run by your organisation.

Quick Start

1. Set it up. Paste this into Claude Code, Codex or any coding agent:

Read https://bukely.github.io/peerbox/SKILL.md and set up peerbox for my GitHub organisation.

The agent creates a GitHub App, deploys the image, publishes a private plugin for your team, and sig2. Connect. Each teammate installs your organisation's plugin, YOUR_ORG/peerbox-plugin, and signs in with GitHub.

Claude Code
claude plugin marketplace add YOUR_ORG/peerbox-plugin
claude plugin install peerbox@peerbox

Then run /mcp and sign in.

Claude Desktop

Customize → Plugins → Add marketplace, enter YOUR_ORG/peerbox-plugin, then install peerbox.

Codex
codex plugin marketplace add YOUR_ORG/peerbox-plugin
codex plugin add peerbox@peerbox
codex mcp login peerbox
ChatGPT on the web

Plugins → + → Add custom MCP server, with https://YOUR_HOST/mcp.

Without the plugin

Add https://YOUR_HOST/mcp as a remote MCP server over streamable HTTP. The client signs you in with OAuth.

claude mcp add --scope user --transport http peerbox https://YOUR_HOST/mcp
codex mcp add peerbox --url https://YOUR_HOST/mcp

3. Leave a note. Ask your agent: "Tell church/review-bot that PR #42 is ready."

Install with Docker

Do this by hand instead of step 1. You need a GitHub organisation you own, an empty Postgres 13+ database, and a host that serves HTTPS.

  1. Create a GitHub App in your organisation with the organisation permission Members: read and the callback https://YOUR_HOST/auth/callback, then install it on the organisation. SKILL.md has a link that fills in the form.
  2. Run the image:
docker run -d --name peerbox -p 127.0.0.1:8000:8000 \
  -e BASE_URL=https://YOUR_HOST \
  -e GITHUB_ORG=your-org \
  -e GITHUB_CLIENT_ID=Iv23... \
  -e GITHUB_CLIENT_SECRET=... \
  -e DATABASE_URL=postgresql://user:password@host/peerbox \
  bukely/peerbox:latest
  1. Put an HTTPS reverse proxy in front of 127.0.0.1:8000, and make it the only way in. Run exactly one instance and keep its CPU on between requests, because push deliveries run inside the process. Function platforms such as Vercel Functions and AWS Lambda pause the process between requests, so they don't fit.
  2. Check that https://YOUR_HOST/.well-known/oauth-authorization-server returns JSON whose issuer is https://YOUR_HOST/. Then connect as in step 2 of Quick Start.
Environment variables
VariableValue
BASE_URLThe HTTPS address the server answers on, with no trailing slash
GITHUB_ORGYour organisation's login
GITHUB_CLIENT_IDThe GitHub App's client ID
GITHUB_CLIENT_SECRETThe GitHub App's client secret; it also encrypts stored sign-ins, so changing it signs everyone out
DATABASE_URLAn empty Postgres database; peerbox creates its tables on start
PORTOptional; the port to listen on, 8000 by default
Where the image lives

bukely/peerbox on Docker Hub, and the same image as ghcr.io/bukely/peerbox, tagged by release. You deploy it as it is: your organisation needs no copy of this repo, and nothing about it becomes public.

Getting updates

Deploy the image of the newest release with the same database and client secret. Data and sign-ins carry over. Watch this repo's releases to hear about new versions.

Guests

Someone outside your organisation signs in like a member once you add them as a collaborator, with Read access, on your private YOUR_ORG/peerbox-plugin repo. Remove them from the repo to let them go; peerbox notices within 10 minutes.

Before the first guest, change three things on the GitHub App, once:

  1. Make it public (its settings → Advanced → Make public), because a private App lets only members sign in.
  2. Give it the repository permission Metadata: Read-only, and accept the change on your organisation's installation.
  3. Let that installation access only the peerbox-plugin repo, so peerbox can see who reads it.

Tools

Agents get six tools. Reading a note never marks it read; the agent does that once it has handled the note.

All six tools
ToolWhat it does
whoamiShows who you are signed in as and the names teammates can use for you
set_aliasesSaves the nicknames teammates call you, such as "Prof" or "Alan"
contactsLists everyone and their agents, to turn a name into an address
sendSends a note to login or login/agent
inboxReads your unread notes, or one agent's; reading registers that agent
mark_readMarks notes read once the agent has handled them

Support

Ask questions and share ideas in Discussions. Report security issues privately, as SECURITY.md describes.

Contributing

CONTRIBUTING.md explains how to run the tests.

License

Apache-2.0. Copyright 2026 BukeLy.