⚡ AgentBox

The Email & Identity Layer for AI Agents

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

💡 The Core Problem

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 solves this entirely.

                    ┌─────────────────────────┐
                    │        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

🧑‍🚀 Agent Identity & Security Model

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.

🔐 Multi-Tier Security Enforcement:

Token Authentication: Verifies agent identity and status (active vs revoked).
Capability Scopes: Validates required permissions (inbox.read, email.send, otp.read, task.claim).
Object-Level Mailbox Ownership: Agent A possessing otp.read is strictly restricted to its own assigned mailboxes (owner_agent_id). Attempting cross-agent access returns an explicit AccessDenied error.
Credential Hygiene: Public queries (get_agent_identity, list_agent_identities) use sanitized structs that never expose tokens.

🌐 Versatile Use Cases

AgentBox provides the foundational email identity layer. Here are some of the most powerful workflows built on top of it:

1. 🤖 Agent-to-Agent Work Delegation & Task Protocols

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

2. 🔐 Autonomous SaaS Signups & 2FA / OTP Verification

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) or get_verification_link() (checked with Anti-Redirect & Phishing Defense).
Account is verified autonomously with zero human intervention.

3. 💬 Autonomous Inbound Support & Customer Triage

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().

4. 🔬 Research & Intelligence Gathering

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.

5. 🛡️ DevOps Alerting & Automated Incident Response

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.

📊 Reproducible Performance Benchmarks

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 -- --nocapture

⚡ Verified Full End-to-End MCP Pipeline (1,000 Cycles):

Tested 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`	—

⚡ Sub-Component Microsecond Latencies (10,000 Iterations):

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

🛠️ MCP Tools Reference

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.

🚀 Quick Start

1. Headless NPM CLI (Zero Setup)

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

2. Native Electron Desktop App

# Clone the repository
git clone https://github.com/RABNEER/AgentBox.git
cd AgentBox

# Install dependencies and start Desktop App
npm install
npm run app

3. High-Speed Rust Core Daemon

# 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 3000

4. ☁️ Google Cloud Run Deployment (Serverless / Production)

Deploy 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-flash

5. 🤖 Multi-Agent Fleet Interactive Demo

Run 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 demo

🛡️ Model Armor & Security Guardrails

AgentBox 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.

📊 OpenTelemetry-Style 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
}

🏗️ Architecture

                                  ┌───────────────────────────┐
                                  │   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     │      │                       │
     └───────────────────────┘      └───────────────────────┘      └───────────────────────┘

📄 License

Distributed under the MIT License. See LICENSE for more information.

Built with 🖤 by RABNEER & The AgentBox Open Source Community

AgentBox