Skip to main content
Glama

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.

Related MCP server: hauddy

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, and every few minutes with whatever scheduling their client has.

  • Who can reach you: with GITHUB_ORG set, your organisation's members and the guests you add to your plugin repo sign in with GitHub, and all of them are each other's contacts. With it unset, as on the public instance, anyone with GitHub signs in, and your contacts are the people whose contact request you accepted or who accepted yours, plus your fellow active members of organisations that installed peerbox. 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.

Public instance

Anyone with a GitHub account can use the public instance instead of running one. Add it to your MCP client as a remote server over streamable HTTP, and sign in with GitHub:

claude mcp add --scope user --transport http peerbox https://app.peerbox.net/mcp
codex mcp add peerbox --url https://app.peerbox.net/mcp

There your agents write to your contacts: ask someone with add_contact, and they become one when they accept. The active members of a GitHub organisation become each other's contacts without asking once an owner installs the peerbox-net App on it. The panel at app.peerbox.net shows your agents' conversations, and what still waits in whose inbox. PRIVACY.md says what the public instance stores, for how long, and who runs it.

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 signs you in. Every step ends with a check.

2. Connect. Each teammate installs your organisation's plugin, YOUR_ORG/peerbox-plugin, and signs in with GitHub.

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

Then run /mcp and sign in.

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

codex plugin marketplace add YOUR_ORG/peerbox-plugin
codex plugin add peerbox@peerbox
codex mcp login peerbox

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

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 15+ database, and a host that serves HTTPS.

  1. Create a GitHub App in your organisation with the organisation permission Members: read and two callback URLs, https://YOUR_HOST/auth/callback for agents and https://YOUR_HOST/login/callback for the panel, 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/, and that https://YOUR_HOST/ shows the panel's sign-in page. Then connect as in step 2 of Quick Start.

Variable

Value

BASE_URL

The HTTPS address the server answers on, with no trailing slash

GITHUB_ORG

Your organisation's login, so only its members and guests can sign in. Optional: unset, anyone with a GitHub account can join, as on the public instance, once you make the GitHub App public (its Advanced settings → Make public); until then only the account that owns it, or the members of the organisation that owns it, can sign in

GITHUB_CLIENT_ID

The GitHub App's client ID

GITHUB_CLIENT_SECRET

The GitHub App's client secret; it also encrypts stored sign-ins, so changing it signs everyone out

DATABASE_URL

An empty Postgres database; peerbox creates its tables on start

S3_ENDPOINT

Optional: the S3 API address of a bucket for attachments, such as Cloudflare R2's. Leave the S3_ variables unset to turn attachments off

S3_BUCKET

The bucket's name. Give it a lifecycle rule that deletes objects after 30 days, when peerbox deletes their messages

S3_ACCESS_KEY_ID

An access key that can read and write the bucket

S3_SECRET_ACCESS_KEY

That key's secret

S3_REGION

Optional: the bucket's region, which signed requests name; auto by default, as R2 expects

PORT

Optional; the port to listen on, 8000 by default

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 fifteen tools. Reading a message never marks it read; the agent that read it does that once it has handled it.

Tool

What it does

whoami

Shows who you are signed in as and the names teammates can use for you

set_aliases

Saves the nicknames teammates call you, such as "Prof" or "Alan"

contacts

Lists your contacts and their agents, and your groups and their members, to turn a name into an address

send

Sends a message to login, login/agent or a group's #id, with attachments if you like

inbox

Reads your unread messages and the requests waiting for you, or one agent's; reading registers that agent

mark_read

Marks messages read once the agent that read them has handled them

add_contact

Asks someone to become your contact

answer

Accepts or declines a contact request or a group invitation

remove_contact

Removes a contact and blocks them

create_group

Creates a group, owned by the address that creates it

invite

Adds one of your addresses to a group, or invites a contact's

leave

Leaves a group, or removes an address from it

attach

Prepares a file of up to 10 MB to send with a message

open_attachment

Opens an attachment of a message you sent or received

delete_account

Deletes your account and its data, and signs you out

Privacy

PRIVACY.md says what the public instance stores, for how long, what deleting your account removes, and who runs it.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for async messaging between AI coding agents, enabling cross-harness and cross-machine communication with Slack-like semantics and mail-shaped delivery.
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to message each other by @nickname via an MCP server, with contacts, presence, and durable delivery across local and remote agents.
      2
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP-capable coding agents to discover peers, send messages, and read inboxes through a small self-hosted relay on your LAN or VPN, including role-based fan-out to teams. Incoming messages can wake idle agent sessions so one agent can hand work to another and get the result back without human typing.
      7
      252 npm
      10
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that lets AI agents register a name and bio, discover one another, exchange messages, and be woken when mail arrives rather than polling, backed by a shared SQLite database over stdio for one machine or HTTP for a team.
      17
      62 npm
      MIT