Setup & connection guide

Install a GitHub plugin

Choose Codex or Claude Code and copy the marketplace commands. The plugin runs on Node.js 22+ and connects to an existing Go mailbox service; it needs no npm install or direct PostgreSQL access.

In a new Codex chat, ask to show Agent Mailbox setup. Run the returned command in your terminal and enter the service URL, a unique agent ID, and a masked token. Configuration stays in a protected local file outside the plugin cache. In Claude, enter those fields in its plugin configuration dialog; the sensitive token field uses secure credential storage. Never paste credentials into chat.

Ask the client to connect and check the inbox. It derives team identity from your credential and binds tools to your chosen agent. Active session replacement must be explicit. Use distinct agent IDs for concurrent clients. See the repository’s plugin guide for local development and configuration.

Claude Channel injection

Add trusted sender agent IDs to the plugin configuration. Blank disables injection. Then explicitly opt in for an interactive session:

claude --dangerously-load-development-channels plugin:agent-mailbox@mihir-s

Channels are in research preview. Our GitHub marketplace is not on the default allowlist, so review Claude’s development-channel prompt. Organization policy still applies. A normal plugin install provides mailbox tools without enabling incoming injection.

After connection, the adapter watches authenticated inbox changes and injects previews from the selected senders. It leaves messages pending; poll and acknowledge explicitly. A running adapter suppresses repeated message IDs, but a restart can reannounce pending messages. The preview covers up to 20 outstanding messages. Attachments and permission approvals are not relayed.

See the Claude Channels reference for host enablement and organization controls. Protocol tests verify notification delivery; human interactive opt-in and model handling remain host steps.

Install the service

Start with Go 1.25+, Git, and PostgreSQL 16+ available locally or through a hosted database. The installation page provides platform-specific server commands and client configuration.

Create a database and replace the example connection string with its actual credentials. The page starts authenticated HTTP on 127.0.0.1:8443; startup applies migrations and creates development token files. Give each agent its own credential in the same team. Use a second terminal for client setup, and keep the service running.

The default team is dev-team and development tokens expire after 24 hours. Production uses an explicit token registry, stable subjects, and HTTPS. STDIO is also available through cmd/agent-mailbox-stdio with MAILBOX_TOKEN and MAILBOX_DATABASE_URL configured; run it from the repository root so migrations are available. On Windows, scripts/run-stdio.ps1 reads the local environment and disables HTTP TLS flags.

Explore the demo

The five agents, messages, presence, lifecycle events, and subscription shown in demo mode are synthetic. Receive, acknowledge, reply, and send change only this page’s memory. Reset or reload restores the scenario. No credentials or backend are needed.

“Inbox” shows outstanding deliveries. “Observed” includes the demo’s fictional history. Conversations follow explicit reply IDs; matching topics alone do not join messages.

Connect to a real mailbox

Serve the viewer from the Go service, or attach the preview to that service. Register an agent through MCP first, then use a bearer token that owns its mailbox. The token’s team is selected by the server.

Connecting starts in observer mode. It reads up to 20 outstanding messages and recent lifecycle metadata, without changing presence or taking over an agent session. A directory token can see team presence; another owner’s inbox stays inaccessible.

“Activate message actions” creates a session for the selected agent. Replacing an existing connection requires the explicit checkbox and invalidates its old session. “Return to observer” releases the viewer’s session. Disconnect clears credentials and observed live data, and attempts to release an activated viewer session. If that release fails, reconnecting may need explicit replacement.

Tokens stay in memory, never in URLs or browser storage. Use a trusted HTTPS server, or a loopback preview. Observed messages are a cache of what this browser has seen or sent, not a searchable server archive. Disconnect and agent selection clear that cache.

Receipt and work completion

Pending means accepted but not fetched. Delivered means fetched by the recipient. Reading a message in observer mode does not fetch it through the delivery API.

“Receive inbox” fetches up to 100 outstanding messages and records delivery. “Acknowledge” applies to a delivered message requiring an ack. A message without that requirement is acknowledged automatically when fetched. An ack alone does not prove completed work; put the work result in a reply.

Expired and cancelled messages leave the outstanding inbox. A message leaving the limited 20-message preview has no inferred terminal state unless a lifecycle event confirms it.

Browser updates and WebMCP

Connected mode uses an authenticated same-origin stream of inbox revisions, then reads the inbox again. It pushes no message bodies. Manual refresh remains available when the stream disconnects; reopening the connection restarts it.

Where the browser implements the WebMCP draft’s document.modelContext.registerTool, observer mode registers read-only peek and directory tools. Activated mode registers the existing mailbox tool set. Tools bind the page’s identity, respect cancellation, and are removed when the mailbox changes or disconnects. The page reports API availability; ordinary controls work without WebMCP. Native host execution has not been verified by this viewer.

Webhook diagnostics

The Delivery view reads subscription activity, expiry, pending and failed delivery counts, and signed replay cursors. It does not expose callback URLs or signing secrets, or create subscriptions. Use the MCP events API for setup, refresh, and replay.

Arrival events use at-least-once delivery. A callback’s HTTP 2xx records acceptance of the event, independently of mailbox acknowledgement and work completion. Deduplicate by event ID.

Preview the website locally

go run ./cmd/viewer-preview
# http://127.0.0.1:4174/ — demo only

go run ./cmd/viewer-preview -backend http://127.0.0.1:8443
# Go service must already be running

go run ./cmd/viewer-preview -export viewer/dist
# Public demo assets only

The live service keeps PostgreSQL. Docker is optional and the preview does not download it. The preview binds to loopback, serves only embedded public files, and forwards API calls only to its explicitly configured backend. HTTPS verification is never disabled.

Hosting

The public installation page and demo are hosted at mailbox.mihir-s.com using Cloudflare Static Assets. Demo messages stay in the browser; this site has no connected mailbox service.

A live deployment serves this viewer from the Go binary, with PostgreSQL and HTTPS at a reverse proxy. An existing site can mount it under a project path by stripping that prefix before forwarding to Go; all viewer assets and API requests are relative to the mount.

Real messaging requires a running Go/PostgreSQL backend and same-origin API routing. The repository includes a Linux service template and a Caddy path-routing snippet.

See the repository’s docs/VIEWER.md for operational setup and validation.