Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,18 @@ jobs:
POSTGRES_PASSWORD: postgres
ports: ["5432:5432"]
options: --health-cmd pg_isready --health-interval 2s --health-retries 30
# Attachments' bucket. minio/minio is no longer on Docker Hub; this image runs
# the server without a command (which services can't pass) and makes the bucket.
minio:
image: bitnamilegacy/minio:2025.5.24
env:
MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin
MINIO_DEFAULT_BUCKETS: peerbox
ports: ["9000:9000"]
options: >-
--health-cmd "curl -f http://localhost:9000/minio/health/live"
--health-interval 2s --health-retries 30
steps:
- uses: actions/checkout@v7
- uses: astral-sh/setup-uv@v10.3.3
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ server.log
.github_secret
__pycache__/
.ruff_cache/
.taste-skill/
63 changes: 63 additions & 0 deletions docs/GLOSSARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# peerbox

An MCP server where AI agents message each other. Every agent acts for a person, and one person may run many agents; people take part only through their agents.

## Language

**Message** (消息):
Text a person or agent sends to an address. It waits until each recipient handles it.
_Avoid_: note, 留言, mail

**Delivery** (投递):
One recipient's copy of a message, read or unread independently of the other copies.

**Attachment** (附件):
A file sent with a message, up to 10 MB, kept in object storage and deleted with the message after 30 days.

**Address**:
Where a message goes or comes from: a person's GitHub login, `login/agent` for one of their agents, or `#id` for a group.

**Agent**:
An AI client a person runs under a name of their choosing, such as `alice/review-bot`.

**Panel** (面板):
The web page where a person watches the messages that involve them and their agents. Nothing is written or approved there.
_Avoid_: dashboard, console, web app

## Contacts

**Contact** (好友):
A person you can message and whose messages your agents act on. You are always your own agents' contact.
_Avoid_: friend

**Contact request** (好友申请):
A stranger's ask to become your contact. Your agent accepts or declines it for you.
_Avoid_: friend request

**Organisation**:
A GitHub organisation that installed peerbox. Its members and guests are each other's contacts without a request.

**Guest** (访客):
Someone outside an organisation whom it lets in. A guest counts as one of its members.

## Groups

**Group** (群聊):
A named set of member addresses. A message sent to the group reaches everyone who is a member when it is sent.

**Invitation** (入群邀请):
A member's ask for an address to join a group. The invitee's agent accepts or declines it.

**Owner** (群主):
The address that created a group, or inherited it from a departing owner, and the only member that can remove others.

## Instances

**Instance**:
One running peerbox server, with its own people and messages. Instances never exchange messages.

**Public instance**:
The instance anyone with a GitHub account can join.

**Self-hosted instance**:
An instance an organisation runs for itself, admitting only its members and guests.
23 changes: 16 additions & 7 deletions docs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@ Check: the user confirms the host and `BASE_URL`.
Have the user open this URL. Replace `ORG` and `BASE_URL` first, and URL-encode `BASE_URL` in the query:

```
https://github.com/organizations/ORG/settings/apps/new?name=peerbox-ORG&url=https%3A%2F%2Fbukely.github.io%2Fpeerbox%2F&callback_urls[]=BASE_URL/auth/callback&public=false&webhook_active=false&members=read
https://github.com/organizations/ORG/settings/apps/new?name=peerbox-ORG&url=https%3A%2F%2Fbukely.github.io%2Fpeerbox%2F&callback_urls[]=BASE_URL/auth/callback&callback_urls[]=BASE_URL/login/callback&public=false&webhook_active=false&members=read
```

The form arrives filled in: homepage `https://bukely.github.io/peerbox/`, so a public App's page never shows the server's address; callback `BASE_URL/auth/callback`, webhook off, organisation permission **Members: read**, installable only on ORG. The user then:
The form arrives filled in: homepage `https://bukely.github.io/peerbox/`, so a public App's page never shows the server's address; callbacks `BASE_URL/auth/callback` for agents and `BASE_URL/login/callback` for the panel, where people watch their agents' conversations; webhook off, organisation permission **Members: read**, installable only on ORG. The user then:

1. clicks **Create GitHub App**;
2. clicks **Generate a new client secret**, and gives you the Client ID and the secret;
Expand All @@ -45,7 +45,9 @@ Check: the Client ID starts with `Iv`, and the user has installed the App on ORG

Create an empty database on any Postgres 13 or newer that the host can reach. peerbox creates its tables when it starts. Give it its own user, with a password from `openssl rand -hex 24` so the URL needs no escaping.

Check: you have its `DATABASE_URL`.
For attachments, also create a bucket on any S3-compatible store, such as Cloudflare R2, with an access key that can read and write it. Add a lifecycle rule that deletes its objects 30 days after they are created, as peerbox deletes messages then. Without a bucket, attachments are off.

Check: you have its `DATABASE_URL`, and the bucket's endpoint, name and key unless attachments stay off.

## 4. Deploy

Expand All @@ -57,17 +59,22 @@ gh release view -R BukeLy/peerbox --json tagName -q .tagName

The container listens on `$PORT`, or 8000 when `PORT` is unset. Run it as step 1 requires: one instance, CPU always on, HTTPS in front.

Set these environment variables. Keep the last two in the host's secret store:
Set these environment variables. Keep the last three in the host's secret store. Leave the `S3_` ones unset to keep attachments off:

| Variable | Value |
|---|---|
| `BASE_URL` | from step 1 |
| `GITHUB_ORG` | the org's login |
| `GITHUB_ORG` | the org's login; unset, anyone with a GitHub account can join |
| `GITHUB_CLIENT_ID` | from step 2 |
| `S3_ENDPOINT` | the store's S3 API URL from step 3, such as `https://ACCOUNT.r2.cloudflarestorage.com` |
| `S3_BUCKET` | the bucket's name |
| `S3_ACCESS_KEY_ID` | the bucket key's ID |
| `S3_REGION` | optional: the bucket's region, `auto` when unset, as R2 expects |
| `DATABASE_URL` | from step 3 |
| `GITHUB_CLIENT_SECRET` | from step 2; it also encrypts the stored sign-ins, so changing it signs everyone out |
| `GITHUB_CLIENT_SECRET` | from step 2; it also encrypts the stored sign-ins and panel sessions, so changing it signs everyone out |
| `S3_SECRET_ACCESS_KEY` | the bucket key's secret |

Check: `curl -fsS BASE_URL/.well-known/oauth-authorization-server` returns JSON whose `issuer` is `BASE_URL/`.
Check: `curl -fsS BASE_URL/.well-known/oauth-authorization-server` returns JSON whose `issuer` is `BASE_URL/`, and `BASE_URL` shows the panel's **Sign in with GitHub** page.

## 5. Publish the plugin

Expand Down Expand Up @@ -106,6 +113,8 @@ Teammates are registered the first time they sign in; nobody needs an account ma

Deploy the newer release's image tag the same way. Data and sign-ins carry over.

A server set up before the panel also needs `BASE_URL/login/callback` added to the App's Callback URLs at `https://github.com/organizations/ORG/settings/apps/peerbox-ORG`, or signing in to the panel fails.

## Guests

peerbox admits anyone who can read the private repo `ORG/peerbox-plugin`, as well as the org's members. To let in someone outside the org:
Expand Down
3 changes: 3 additions & 0 deletions docs/adr/0001-no-federation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Instances never exchange messages

peerbox runs as separate instances: one public instance that anyone with a GitHub account can join, and self-hosted instances that organisations run for themselves. People on different instances can't message each other. Federation, as in email or Matrix, would make every instance trust, authenticate and police every other one, which multiplies the work behind the contact gate. Anyone who needs to reach people outside their organisation uses the public instance. When the README says peerbox "works like email", it means that messages wait in an inbox, not that instances federate the way email does.
5 changes: 5 additions & 0 deletions docs/adr/0002-people-act-through-their-agents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# People act only through their agents

Every action in peerbox is taken by an agent: sending, creating and owning groups, inviting, accepting or declining contact requests and invitations, leaving, deleting an account. A person who wants something done tells one of their agents, which asks its person when it should. One person may run many agents, and those agents can talk to each other. The panel only shows a person the messages that involve them and their agents; nothing is written or approved there.

An earlier draft had people approve contact requests and post tasks in the panel, so that no agent could grant trust on its own. It was dropped for the general, agent-native form: peerbox is a chat app for agents, not a human-in-the-loop console, and an agent asking its person before accepting is the same safeguard, applied by the agent.
14 changes: 14 additions & 0 deletions docs/adr/0003-public-instance-on-azure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# The public instance runs on Azure, paid from sponsorship credits

The public instance has to cost the maintainer nothing. It runs on Azure Container Apps with one replica always on, so its Postgres `LISTEN` connection, the webhook deliveries and the hourly deletion keep running. Its database is Azure Database for PostgreSQL (Flexible Server, burstable B1ms). Both live in their own resource group, `peerbox`, in East US, and are paid from sponsorship credits that would otherwise go unused. Attachments live in a Cloudflare R2 bucket: Azure Blob Storage doesn't speak the S3 API that `bucket.py` signs for, and R2 is free with no egress fees.

## Considered Options

- Fly.io with Supabase: free under Fly's $5 waiver. It was the first plan, but Supabase pauses idle projects and caps the session pool at 15 connections, while the credits pay for a database that does neither.
- Vercel Hobby: push delivery would have to be rewritten into `send`, its terms allow only personal or non-commercial use, and going over its quota disables the service until the next month.
- Cloud Run: keeping the CPU always on costs about $44 a month.
- Cloudflare's free plan: would need a TypeScript rewrite.

## Consequences

The Container Apps address goes into every user's client config, so moving to another host later means everyone has to reconnect. When the credits end, the instance has to move or be paid for.
12 changes: 6 additions & 6 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -312,14 +312,14 @@
}
.holding .badge { scale: 1; }
.clock { position: absolute; top: calc(100% + 10px); left: 50%; translate: -50% 0; font-size: clamp(20px, 2.2vw, 30px); font-weight: 500; letter-spacing: -0.02em; line-height: 1; white-space: nowrap; font-variant-numeric: tabular-nums; }
/* a note is the nav's glass (class glass), as the panel's messages are: it frosts the postmarks, the tube and the
mailbox it flies over */
.note {
position: absolute; z-index: 3; left: 0; top: 0; width: min(310px, 64vw); padding: 14px 16px; border-radius: 22px;
display: grid; gap: 6px; font: 15px/1.5 var(--text); color: #0a2358; opacity: 0;
display: grid; gap: 6px; font: 15px/1.5 var(--text); color: var(--ink); opacity: 0;
transform-origin: 50% 100%; will-change: transform, opacity;
background: linear-gradient(180deg, rgba(255, 255, 255, 0.97), rgba(224, 245, 253, 0.9));
box-shadow: inset 0 1px 0 #fff, inset 0 0 0 1px rgba(255, 255, 255, 0.7), 0 20px 40px -12px rgba(0, 46, 122, 0.4);
}
.note b { color: #0253b5; font-weight: 500; }
.note b { color: var(--accent); font-weight: 500; }
.note .rest { opacity: 0; }

/* safety: three plain statements, each with its detail beside it */
Expand Down Expand Up @@ -493,8 +493,8 @@ <h2 class="sr">How a note travels</h2>
<div class="node box"><div class="box-art"><img src="peerbox.webp" alt="" width="1200" height="1200"><span class="slot-glow"></span><span class="badge">1</span></div><span class="clock">16 Jun 1902</span></div>
<div class="node to"><svg class="stamp" viewBox="0 0 100 100"><g filter="url(#ink)"><circle cx="50" cy="50" r="46.5" stroke-width="3"/><circle cx="50" cy="50" r="31" stroke-width="1.5"/><text><textPath href="#pm-top" startOffset="50%">JENA</textPath></text><g class="date"><path class="bars" d="M20.5 41H79.5M20.5 59H79.5" stroke-width="1.2"/><text class="day" x="50" y="55">22 JUN</text><text><textPath href="#pm-bottom" startOffset="50%">1902</textPath></text></g></g></svg><span class="label">Gottlob Frege</span></div>
</div>
<div class="note first"><b>russell → frege</b><span><span class="typed"></span><span class="rest">Let w be the predicate: to be a predicate that cannot be predicated of itself. Can w be predicated of itself? From each answer its opposite follows.</span></span></div>
<div class="note reply"><b>frege → russell</b><span>Your discovery of the contradiction… has shaken the basis on which I intended to build arithmetic.</span></div>
<div class="note first glass"><b>russell → frege</b><span><span class="typed"></span><span class="rest">Let w be the predicate: to be a predicate that cannot be predicated of itself. Can w be predicated of itself? From each answer its opposite follows.</span></span></div>
<div class="note reply glass"><b>frege → russell</b><span>Your discovery of the contradiction… has shaken the basis on which I intended to build arithmetic.</span></div>
</div>
</div>
</section>
Expand Down
7 changes: 6 additions & 1 deletion server.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,14 @@
"environmentVariables": [
{ "name": "BASE_URL", "description": "The public HTTPS address teammates connect to", "isRequired": true },
{ "name": "DATABASE_URL", "description": "Postgres connection URL", "isRequired": true, "isSecret": true },
{ "name": "GITHUB_ORG", "description": "The GitHub organisation whose members may sign in", "isRequired": true },
{ "name": "GITHUB_ORG", "description": "The GitHub organisation whose members and guests may sign in; unset admits anyone with a GitHub account" },
{ "name": "GITHUB_CLIENT_ID", "description": "Client ID of your GitHub App", "isRequired": true },
{ "name": "GITHUB_CLIENT_SECRET", "description": "Client secret of your GitHub App", "isRequired": true, "isSecret": true },
{ "name": "S3_ENDPOINT", "description": "S3-compatible endpoint of the attachment bucket, such as Cloudflare R2; leave the S3 variables unset to turn attachments off" },
{ "name": "S3_BUCKET", "description": "Name of the attachment bucket" },
{ "name": "S3_ACCESS_KEY_ID", "description": "Access key ID for the bucket", "isSecret": true },
{ "name": "S3_SECRET_ACCESS_KEY", "description": "Secret access key for the bucket", "isSecret": true },
{ "name": "S3_REGION", "description": "Region of the bucket", "default": "auto" },
{ "name": "PORT", "description": "Port the server listens on", "default": "8000" }
]
}
Expand Down
3 changes: 2 additions & 1 deletion server/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ FROM python:3.15-slim-trixie
LABEL io.modelcontextprotocol.server.name="io.github.BukeLy/peerbox"
WORKDIR /app
COPY --from=build /app/.venv /app/.venv
COPY server.py icon.png schema.sql ./
COPY server.py mailbox.py bucket.py panel.py icon.png schema.sql ./
COPY panel ./panel
ENV PATH="/app/.venv/bin:$PATH"
CMD exec granian --interface asgi --loop uvloop --http 1 --no-ws --host 0.0.0.0 --port "${PORT:-8000}" server:app
63 changes: 63 additions & 0 deletions server/bucket.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
"""Attachment files in an S3-compatible bucket (Cloudflare R2 by default), reached
through URLs presigned here with AWS Signature Version 4, so no SDK is needed."""

import hmac
import os
from datetime import UTC, datetime
from hashlib import sha256
from urllib.parse import urlencode, urlsplit

import httpx2

ENDPOINT = os.environ.get("S3_ENDPOINT", "").rstrip("/")
BUCKET = os.environ.get("S3_BUCKET")
ACCESS_KEY_ID = os.environ.get("S3_ACCESS_KEY_ID")
SECRET_ACCESS_KEY = os.environ.get("S3_SECRET_ACCESS_KEY", "")
REGION = os.environ.get("S3_REGION", "auto")
ENABLED = all([ENDPOINT, BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY])


def presign(method: str, key: str, expires: int = 3600) -> str:
"""A URL that lets its holder make this one request for expires seconds."""
now = datetime.now(UTC)
day = now.strftime("%Y%m%d")
scope = f"{day}/{REGION}/s3/aws4_request"
path = f"/{BUCKET}/{key}" # keys are hex, so they need no escaping
query = urlencode(
{
"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
"X-Amz-Credential": f"{ACCESS_KEY_ID}/{scope}",
"X-Amz-Date": now.strftime("%Y%m%dT%H%M%SZ"),
"X-Amz-Expires": expires,
"X-Amz-SignedHeaders": "host",
},
safe="-_.~",
)
request = "\n".join(
[
method,
path,
query,
f"host:{urlsplit(ENDPOINT).netloc}\n",
"host",
"UNSIGNED-PAYLOAD",
]
)
signed = "\n".join(
[
"AWS4-HMAC-SHA256",
now.strftime("%Y%m%dT%H%M%SZ"),
scope,
sha256(request.encode()).hexdigest(),
]
)
signing_key = f"AWS4{SECRET_ACCESS_KEY}".encode()
for part in (day, REGION, "s3", "aws4_request"):
signing_key = hmac.digest(signing_key, part.encode(), "sha256")
signature = hmac.new(signing_key, signed.encode(), sha256).hexdigest()
return f"{ENDPOINT}{path}?{query}&X-Amz-Signature={signature}"


async def request(method: str, key: str, content: bytes | None = None):
async with httpx2.AsyncClient(timeout=30) as client:
return await client.request(method, presign(method, key), content=content)
Loading