beeperbox

                ╭──────────────────────────────────╮
                │  ╔╗ ╔═╗╔═╗╔═╗╔═╗╦═╗╔╗ ╔═╗ ╦ ╦    │
                │  ╠╩╗╠╣ ╠╣ ╠═╝╠╣ ╠╦╝╠╩╗║ ║ ╚╦╝    │
                │  ╚═╝╚═╝╚═╝╩  ╚═╝╩╚═╚═╝╚═╝ ╩ ╩    │
                │   one agent ──→ 50+ messengers   │
                ╰──────────────────────────────────╯

One Docker container that plugs your AI agent into 50+ messengers through a single MCP endpoint.

WhatsApp, iMessage, Signal, Telegram, Discord, Slack, Messenger, Instagram, LinkedIn, Google Messages, Matrix — everything Beeper bridges, reachable from one HTTP or MCP endpoint instead of 50 per-platform SDKs, OAuth dances, and rate-limit quirks. If you only need Telegram, this is overkill — use openclaw or any BotFather library. If you need reach across many networks from one agent, keep reading.

Quick start

Prereqs: Docker + compose plugin, ~1 GB disk, ~600 MB RAM, a Beeper account.

1. Pull and run

curl -LO https://raw.githubusercontent.com/hamr0/beeperbox/master/docker-compose.yml
docker compose up -d

Pulls the pre-built multi-arch image (ghcr.io/hamr0/beeperbox:latest, linux/amd64 + linux/arm64). No clone, no build. Pin a version with BEEPERBOX_IMAGE_TAG=0.5.0 docker compose up -d, or track master with :edge (may break).

2. Log in once

Open http://localhost:6080/vnc.html, sign into Beeper, then Settings → Developers → enable the API and create an access token. Save it:

echo "BEEPER_TOKEN=abc123..." > .env
docker compose up -d

Login and bridge state persist in a named volume — you won't log in again after restarts.

3. Talk to it

# Raw Beeper Desktop API
curl -H "Authorization: Bearer $BEEPER_TOKEN" http://localhost:23373/v1/info

# MCP server (HTTP transport)
curl -X POST http://localhost:23375 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For stdio MCP, point any MCP client at docker exec -i beeperbox node /opt/mcp/server.js --stdio. Works with Claude Code, Cursor, Cline, Continue, bareagent, or anything that speaks Model Context Protocol.

Done.

Ports

All three are env-overridable (BEEPERBOX_NOVNC_PORT, BEEPERBOX_HOST_PORT, BEEPERBOX_MCP_PORT) so you can run multiple instances on one VPS. For remote access use SSH tunnel, Tailscale, or a TLS reverse proxy — never drop the 127.0.0.1 prefix.

Build from source

Only if you're hacking on the image itself or running air-gapped:

git clone https://github.com/hamr0/beeperbox.git && cd beeperbox
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

Docs

• docs/GUIDE.md — human walkthrough: first-run login, multi-instance VPS pattern, read-only vs read-write tokens, troubleshooting
• beeperbox.context.md — drop-in integration guide for AI assistants: MCP tools, schemas, wiring snippets for Claude Code / Cursor / Cline / bareagent, error codes
• CHANGELOG.md — version history and versioning policy. tl;dr MINOR = new runtime behavior (new MCP tool, new architecture, new transport), PATCH = bug fixes + packaging + docs. MAJOR held at 0 until the MCP tool set and HTTP API are declared stable.

The bare ecosystem

Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone.

Core — the brain, the gate, the memory.

• bareagent — the think→act→observe loop. Goal in → coordinated actions out. Replaces LangChain, CrewAI, AutoGen.
• bareguard — the single gate every action passes through. Action in → allow / deny / ask-a-human out. Replaces hand-rolled allowlists and scattered policy code.
• litectx — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). Query in → ranked context out.

Optional reach — give the agent hands.

• barebrowse — a real browser for agents. URL in → pruned snapshot out. Replaces Playwright, Selenium, Puppeteer.
• baremobile — Android + iOS device control. Screen in → pruned snapshot out. Replaces Appium, Espresso, XCUITest.
• beeperbox — 50+ messaging networks via one MCP server (headless Beeper Desktop in Docker). Chat in → unified message stream out. Replaces Twilio, per-platform bot APIs.

License

Apache-2.0. Independent wrapper around Beeper Desktop, no affiliation with Beeper / Automattic.

Related

• Beeper Desktop — upstream app this containerizes
• Beeper Desktop API — official API reference
• bareagent — lightweight agent orchestration that consumes beeperbox via MCP
• multis — personal-assistant project that drove beeperbox's extraction