Auth
March 20, 2026 · View on GitHub
There are many claws, but this one is mine.
Mercury is a personal AI assistant that lives where you chat. It connects to WhatsApp, Slack, and Discord, runs pi as a sandboxed subprocess, and deploys as a single Docker container.
Quick Start
npm install -g mercury-ai
mkdir my-assistant && cd my-assistant
mercury init
Configure .env:
MERCURY_BOT_USERNAME=Mercury
MERCURY_TRIGGER_PATTERNS=@Mercury,Mercury
MERCURY_MODEL_PROVIDER=anthropic
MERCURY_ENABLE_WHATSAPP=true
Authenticate:
mercury auth login anthropic # OAuth (opens browser)
mercury auth whatsapp # WhatsApp QR code
Build and start:
mercury build # Build Docker image with extensions
mercury start # Start container
mercury logs -f # View logs
Pair via WhatsApp DM:
mercury pair # Show pairing code
# Send "/pair <CODE>" in a WhatsApp DM → grants admin
# Send "/pair <CODE>" in a group → activates the bot there
How It Works
┌──────────────────────────────────────────────────────────────────┐
│ Docker Container │
│ │
│ ┌──────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐ │
│ │ WhatsApp │ │ Slack │ │ Discord │ │ API │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │ /chat │ │
│ └────┬─────┘ └─────┬───┘ └────┬────┘ └────┬──┘ │
│ └──────────────┴───────────┴────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ Ingress │ │
│ │ pairing · commands · │ │
│ │ ambient · routing │ │
│ └────────────┬────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ Policy │ │
│ │ triggers · permissions │ │
│ │ mutes · rate limits │ │
│ └────────────┬────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ │
│ │ Runtime │ │
│ │ messages · hooks · │ │
│ │ RBAC env · history │ │
│ └────────────┬────────────┘ │
│ │ │
│ ┌────────────▼────────────┐ ┌───────────────┐ │
│ │ pi subprocess │────▶│ SQLite DB │ │
│ │ (sandboxed) │ │ messages, │ │
│ │ mrctl · extensions │ │ tasks, │ │
│ └─────────────────────────┘ │ roles, ... │ │
│ └───────────────┘ │
└──────────────────────────────────────────────────────────────────┘
Features
| Feature | Description | Docs |
|---|---|---|
| Multi-platform | WhatsApp, Slack, Discord, or CLI-only | pipeline |
| API key auth | All endpoints require Bearer token | auth |
| Pairing | DM pairing for admin, group pairing for activation | permissions |
| RBAC | Role-based permissions, extension CLI blocking | permissions |
| Scheduled tasks | Cron + one-shot tasks with conversation targeting | scheduler |
| Media | Images, documents, voice notes in/out | media |
| Extensions | CLIs, skills, jobs, hooks, config, widgets | extensions |
| Ambient context | Non-triggering group messages stored for context | pipeline |
| Sandbox | bubblewrap (Linux) / sandbox-exec (macOS) | agent lifecycle |
CLI
# Project
mercury init # Initialize project
mercury build # Build Docker image
mercury start # Start container
mercury stop # Stop container
mercury restart # Rebuild + restart
mercury logs [-f] # View logs
mercury status # Check status
mercury doctor # Preflight checks
# Auth
mercury auth login [provider] # OAuth login
mercury auth whatsapp # WhatsApp QR/pairing code
mercury auth status # Show auth status
# Chat (direct API)
mercury chat "hello" # Send message
mercury chat -f photo.jpg "?" # With file attachment
echo "query" | mercury chat # Piped input
# Conversations
mercury pair # Show pairing code
mercury convos list # List conversations
mercury convos unpair <id> # Unpair a conversation
# Extensions
mercury ext add <source> # Install (path, npm:, git:)
mercury ext remove <name> # Remove
mercury ext list # List installed
# API Keys
mercury api-keys create <name> # Create key (shown once)
mercury api-keys list # List keys (prefix only)
mercury api-keys revoke <id> # Revoke a key
mrctl (agent-side CLI)
Used by the agent inside the sandbox to manage Mercury:
mrctl whoami # Caller identity + permissions
mrctl tasks list|create|pause|resume|run|delete
mrctl roles list|grant|revoke
mrctl permissions show|set
mrctl config get|set
mrctl conversations # List conversations
mrctl mute|unmute|mutes # User moderation
mrctl stop # Abort current run
mrctl compact # Reset session
Extensions
mercury ext add git:github.com/Michaelliv/mercury-extensions#packages/knowledge
mercury ext add git:github.com/Michaelliv/mercury-extensions#packages/web-browser
mercury ext add git:github.com/Michaelliv/mercury-extensions#packages/charts
mercury ext add git:github.com/Michaelliv/mercury-extensions#packages/github
Each extension exports a setup function:
export default function(mercury) {
mercury.cli({ name: "napkin", install: "bun add -g napkin-ai" });
mercury.permission({ defaultRoles: ["admin", "member"] });
mercury.env({ from: "MERCURY_NAPKIN_API_KEY" });
mercury.skill("./skill");
mercury.on("workspace_init", async ({ workspace }) => { ... });
mercury.job("distill", { interval: 3600_000, run: async (ctx) => { ... } });
}
Extension CLIs are installed into the Docker image at build time. RBAC blocks denied CLIs at the bash level. See docs/extensions.md.
Configuration
| Variable | Default | Description |
|---|---|---|
MERCURY_BOT_USERNAME | mercury | Bot display name |
MERCURY_PORT | 3000 | Server port |
MERCURY_MODEL_PROVIDER | anthropic | AI provider |
MERCURY_MODEL | claude-sonnet-4-20250514 | Model |
MERCURY_TRIGGER_PATTERNS | @Mercury,Mercury | Trigger words |
MERCURY_TRIGGER_MATCH | mention | mention / prefix / always |
MERCURY_ENABLE_WHATSAPP | false | Enable WhatsApp adapter |
MERCURY_ENABLE_DISCORD | false | Enable Discord adapter |
MERCURY_ENABLE_SLACK | false | Enable Slack adapter |
MERCURY_RATE_LIMIT_PER_USER | 0 (disabled) | Requests per window |
MERCURY_AGENT_TIMEOUT_MS | 900000 (15 min) | Agent subprocess timeout |
Docs
- Deployment guide
- Agent lifecycle
- Message pipeline
- Permissions & RBAC
- Extensions
- Scheduled tasks
- Authentication
- Memory
- Media handling
- Rate limiting
- Graceful shutdown
- Platform setup: WhatsApp · Discord · Slack
License
MIT