AgentBox gives any autonomous AI agent (Claude Code, Cursor, Antigravity, OpenAI Swarm) its own machine-native email identity, inbox, outbound communication, authentication, and event-driven email capabilities — self-hosted, sovereign, and blazingly fast.
Quick Start • Core Abstraction • Agent Identity & Security • Use Cases • Benchmarks • MCP Tools • Architecture
Autonomous AI agents need a way to interact with the human world and each other. Today, email is the universal communication protocol across all software and platforms:
- How does a browser agent verify its account on GitHub or AWS? Email.
- How does a customer contact your AI support assistant? Email.
- How does an external QA agent delegate a bug report to a coding agent? Email.
- How does a research agent receive arXiv digests and industry alerts? Email.
Without machine-native email infrastructure, developers are forced to use brittle API polling, hack personal Gmail inboxes, or manually click verification links.
┌─────────────────────────┐
│ AGENTBOX │
└────────────┬────────────┘
│
┌──────────────────┴──────────────────┐
▼ ▼
🧑🚀 IDENTITY 📬 COMMUNICATION
• User-Defined Name & Email • Inbound Inbox (SMTP/IMAP/HTTP)
• Persistent Agent ID • Outbound SMTP Relay
• Scoped Capability Matrix • Realtime Event Bus (<0.001ms)
• Object-Level Ownership • OTP Isolator & SafeLink Engine
│ │
└──────────────────┬──────────────────┘
│
▼
Autonomous AI Agent
AgentBox does not prescribe who your agent is. You define the agent's name, email, and capability policy:
# 1. Create a Support Agent with a custom company email
npx agentbox-mail agent create support \
--email support@mycompany.com \
--capabilities "inbox.read,email.send"
# 2. Create an Autonomous Coding Agent
npx agentbox-mail agent create coder \
--email coder@mycompany.com \
--capabilities "inbox.read,task.claim,task.update,otp.read"
# 3. Create a Browser QA Agent with standard verification permissions
npx agentbox-mail agent create browser-qa \
--capabilities "inbox.read,otp.read,links.read"╔══════════════════════════════════════════════════════════════════╗
║ 🧑🚀 AGENT IDENTITY PROVISIONED ║
╠══════════════════════════════════════════════════════════════════╣
║ Agent ID : agent_coder_7f92a1 ║
║ Name : coder ║
║ Email : coder@mycompany.com ║
║ Auth Token : agb_92d7e8f1c3a04b12 ║
║ Capabilities : ["inbox.read", "task.claim", "otp.read"] ║
║ Status : active ║
╚══════════════════════════════════════════════════════════════════╝
⚠️ NOTE: Store this auth_token securely. It is only displayed once upon creation.
- Token Authentication: Verifies agent identity and status (
activevsrevoked). - Capability Scopes: Validates required permissions (
inbox.read,email.send,otp.read,task.claim). - Object-Level Mailbox Ownership: Agent A possessing
otp.readis strictly restricted to its own assigned mailboxes (owner_agent_id). Attempting cross-agent access returns an explicitAccessDeniederror. - Credential Hygiene: Public queries (
get_agent_identity,list_agent_identities) use sanitized structs that never expose tokens.
AgentBox provides the foundational email identity layer. Here are some of the most powerful workflows built on top of it:
An external QA or discovery agent (like Jules) sends an email with a bug or feature request. AgentBox's built-in TaskDetector automatically parses the subject ([TASK:BUG]), extracts the repository, branch, priority, and line citations, provisions an AgentTask, and wakes the Coding Agent via the event bus:
Jules (QA Agent)
│
│ 1. Sends email: "[TASK:BUG] Fix duplicate property filter in EstateFlow"
│ Body: "Repository: RABNEER/EstateFlow\nPriority: high\nEvidence: tests/search.spec.ts:87"
▼
┌─────────────────┐
│ AgentBox │ ──► Auto-detects Work Order via `TaskDetector`
└────────┬────────┘ ──► Provisions `AgentTask` & records audit event
│
│ 2. Realtime Event Bus Dispatch (<0.001ms) / SSE Daemon Bridge
▼
Coder (Worker Agent / Claude Code)
│ 3. Instantaneously claims task via `claim_agent_task`
│ 4. Fixes code, opens GitHub PR, calls `update_task_progress`
│ 5. Calls `complete_agent_task` with CI results
▼
┌─────────────────┐
│ AgentBox │ ──► Status: "completed" + Immutable Audit Lineage
└────────┬────────┘
│ 6. Emits completion notification to Jules / User
▼
Jules closes ticket
Browser agents (Puppeteer, Playwright, Stagehand) need to sign up for tools, verify email addresses, and solve OTP challenges:
- Agent creates inbox
create_agent_inbox(name: "signup-bot"). - Triggers signup on platform (e.g. AWS, Stripe, Vercel).
- Calls
get_latest_otp()(extracted via regex in <0.14ms) orget_verification_link()(checked with Anti-Redirect & Phishing Defense). - Account is verified autonomously with zero human intervention.
Give your customer support agent its own email address (support@yourcompany.com):
- Customer emails support with an issue.
- AgentBox ingests the email via raw SMTP or IMAP sync.
- Realtime SSE event notifies the support agent.
- Agent analyzes the inquiry, consults internal docs, and replies via
send_agent_email().
Give your research agent an identity (researcher@yourcompany.com):
- Subscribes to industry newsletters, security advisories (CVEs), and arXiv digest feeds.
- Agent reads inbound emails periodically using
read_agent_inbox(). - Synthesizes executive briefings, summarizes findings, and forwards digests to your team.
Give your incident response agent an identity (oncall@yourcompany.com):
- Receives critical error alerts from Datadog, Sentry, or PagerDuty.
- Realtime event hook wakes the agent immediately.
- Agent queries logs, identifies the failing commit, and dispatches a fix order to the coding agent.
AgentBox includes a complete benchmark test suite (tests/benchmark.rs) measuring the entire pipeline from raw bytes to full JSON-RPC output:
cargo test --release --test benchmark -- --nocaptureTested Pipeline: Raw MIME Ingestion ➔ mail-parser ➔ SafeLink Analysis ➔ Regex OTP ➔ SQLite INSERT ➔ Broadcast Dispatch ➔ Authenticated MCP Tool Call (tools/call) ➔ JSON-RPC Result Output
| Pipeline Metric | Measured Latency | Throughput |
|---|---|---|
| Average (Mean) | 451.9 µs (0.451 ms) |
2,213 complete MCP cycles/sec |
| p50 Median | 431.5 µs (0.431 ms) |
— |
| p95 | 586.2 µs (0.586 ms) |
— |
| p99 | 1.04 ms |
— |
- Event Bus Channel Dispatch:
0.216 µs(0.0002 ms) — 4.62 Million events/sec - Link Safety & Anti-Redirect:
0.652 µs(0.0007 ms) — 1.53 Million checks/sec - OTP Regex Extraction:
138.2 µs(0.138 ms) — 7,230 extractions/sec
AgentBox implements the Model Context Protocol (MCP) specification over stdio:
| Category | Tool | Parameters | Description |
|---|---|---|---|
| Identity | create_agent_identity |
name, email?, capabilities? |
Creates a persistent identity with custom/auto email and returns a one-time auth token. |
| Identity | get_agent_identity |
agent_id |
Retrieves public agent metadata (tokens are sanitized). |
| Identity | list_agent_identities |
— | Lists all registered public agent identities and active policies. |
| Identity | revoke_agent_identity |
agent_id |
Revokes an agent identity and invalidates its auth token immediately. |
| Mailbox | create_agent_inbox |
name, address?, agent_token? |
Creates a new virtual mailbox linked to the calling agent identity. |
| Mailbox | get_latest_otp |
account_id, agent_token? |
Extracts the newest 4–8 digit verification code in <0.14ms with ownership check. |
| Mailbox | wait_for_email |
account_id, timeout_secs?, agent_token? |
Event-Driven Hook: Async Tokio broadcast channel wakes the agent in <0.001ms. |
| Mailbox | get_verification_link |
account_id, agent_token? |
Returns parsed activation links with Deep Link Safety & Anti-Redirect Defense. |
| Mailbox | read_agent_inbox |
account_id, limit?, agent_token? |
Retrieves recent messages, full body text, HTML, and sender metadata. |
| Mailbox | send_agent_email |
account_id, to, subject, body, agent_token? |
Dispatches outbound emails via SMTP relay with capability authorization. |
| Mailbox | delete_agent_inbox |
account_id, agent_token? |
Deletes a temporary mailbox and purges stored messages. |
| Task Protocol | dispatch_agent_task |
action, description, repository?, branch?, priority?, target_agent?, evidence?, acceptance_criteria?, agent_token? |
Dispatches a structured work order from one agent to another. |
| Task Protocol | claim_agent_task |
task_id, agent_token |
Atomically locks and assigns a task to the claiming worker agent. |
| Task Protocol | update_task_progress |
task_id, status, commit_sha?, pr_url?, test_results?, note?, agent_token |
Updates task status (running, testing, pr_opened) and records audit log. |
| Task Protocol | complete_agent_task |
task_id, summary, commit_sha?, pr_url?, test_results?, agent_token |
Closes a task with completion details and emits completion event. |
| Task Protocol | list_agent_tasks |
status?, agent_token?, limit? |
Lists tasks filtered by lifecycle state or agent identity. |
| Task Protocol | get_task_audit_trail |
task_id, agent_token? |
Retrieves the immutable audit log and lifecycle history for a task. |
Instantly auto-configure your AI tools in 1 second:
# 1-Click Auto-Install MCP Server & AI Skill into Claude Code, Cursor, Antigravity
npx agentbox-mail init
# Start MCP stdio server with live daemon SSE event bridge
npx agentbox-mail mcp
# Create an Agent Identity with scoped capabilities
npx agentbox-mail agent create support --email support@mycompany.com --capabilities "inbox.read,email.send"
# Retrieve latest OTP code
npx agentbox-mail otp agent@yourdomain.com
# Launch Web Dashboard
npx agentbox-mail ui# Clone the repository
git clone https://github.com/RABNEER/AgentBox.git
cd AgentBox
# Install dependencies and start Desktop App
npm install
npm run app# Build the optimized production binary
cargo build --release
# Start all-in-one daemon (HTTP Port 3000 + SMTP Port 2525)
./target/release/agentbox-mail server --port 3000Deploy AgentBox on Google Cloud Run with persistent telemetry and Gemini 3.5 in under 60 seconds:
# 1. Build and push container to Google Artifact Registry
gcloud builds submit --tag gcr.io/$GOOGLE_CLOUD_PROJECT/agentbox-mail
# 2. Deploy to Cloud Run with Healthcheck Probes & Gemini API
gcloud run deploy agentbox \
--image gcr.io/$GOOGLE_CLOUD_PROJECT/agentbox-mail \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--port 8080 \
--set-env-vars DOMAIN=agentbox.run.app,GEMINI_API_KEY=$GEMINI_API_KEY,GEMINI_MODEL=gemini-2.5-flashRun the end-to-end multi-agent orchestration demo showing Gemini 3.5 Triage → Model Armor Scan → Coder Execution → QA Testing → Gemini Resolution Composer:
npm run demoAgentBox includes inline security inspection designed for autonomous agent operations:
- Prompt Injection & Jailbreak Defense: Regex & semantic detection of delimiter attacks, system prompt overrides, and role-hijacking attempts.
- PII & Secret Sanitization: Inline redaction of API keys (
sk-*,ghp_*,agb_*), Bearer tokens, Credit Card numbers, and SSNs before payloads reach downstream LLMs. - Immutable Security Audit Log: Blocked threats and redaction counts are immutably recorded to SQLite (
task_audit_logs) and exposed via/v1/observability.
Exposes real-time fleet health, task counts, and latency statistics via GET /v1/observability:
{
"total_accounts": 12,
"total_agent_identities": 5,
"total_messages": 142,
"total_tasks": 38,
"tasks_received": 2,
"tasks_claimed": 1,
"tasks_running": 3,
"tasks_completed": 31,
"tasks_failed": 1,
"total_audit_events": 218,
"model_armor_security_events": 4,
"system_status": "operational",
"p95_latency_ms": 0.586,
"mcp_throughput_cycles_sec": 2213
} ┌───────────────────────────┐
│ Inbound Emails & Tasks │
└─────────────┬─────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ Hostinger / Titan / │ │ Raw SMTP Listener │ │ Inbound HTTP Webhook │
│ Google IMAP TLS (993) │ │ (0.0.0.0:2525) │ │ (POST /v1/inbound) │
└───────────┬───────────┘ └───────────┬───────────┘ └───────────┬───────────┘
│ │ │
└──────────────────────────────┼──────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ High-Speed Parser Engine │
│ • 4–8 Digit OTP Isolator │
│ • Link Safety Engine │
│ • TaskDetector (Work Order)│
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ Embedded SQLite Storage │
│ (`agentbox.db`) │
│ • Identities & Auth Tokens │
│ • Mailboxes & Messages │
│ • Resource Ownership Graph │
│ • Agent Tasks & Audit Logs │
└──────────────┬──────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ Realtime SSE Bus │ │ MCP Server (stdio) │ │ Native Desktop App / │
│ (`GET /v1/events`) │ │ Full Tool Interface │ │ Web Dashboard (:3000) │
│ (Live Daemon Bridge) │ │ Object-Level Auth │ │ │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
Distributed under the MIT License. See LICENSE for more information.
Built with 🖤 by RABNEER & The AgentBox Open Source Community