AgentBox
by RABNEER
README.md
<div align="center">
<img src="assets/agentbox_banner.jpg" alt="AgentBox Banner" width="100%" style="border-radius: 12px; margin-bottom: 20px;" />
# ⚡ AgentBox
### *The Email & Identity Layer for AI Agents*
[](https://github.com/RABNEER/AgentBox/actions)
[](https://www.npmjs.com/package/agentbox-mail)
[](https://www.npmjs.com/package/agentbox-mail)
[](https://github.com/RABNEER/AgentBox/releases/latest)
[](https://www.rust-lang.org/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
<br/>
**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.
<br/>
[Quick Start](#-quick-start) • [Core Abstraction](#-core-abstraction) • [Agent Identity & Security](#-agent-identity--security-model) • [Use Cases](#-versatile-use-cases) • [Benchmarks](#-reproducible-performance-benchmarks) • [MCP Tools](#-mcp-tools-reference) • [Architecture](#-architecture)
---
</div>
<br/>
## 💡 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
```
<br/>
---
## 🧑🚀 Agent Identity & Security Model
AgentBox does not prescribe who your agent is. **You define the agent's name, email, and capability policy:**
```bash
# 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:
1. **Token Authentication**: Verifies agent identity and status (`active` vs `revoked`).
2. **Capability Scopes**: Validates required permissions (`inbox.read`, `email.send`, `otp.read`, `task.claim`).
3. **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.
4. **Credential Hygiene**: Public queries (`get_agent_identity`, `list_agent_identities`) use sanitized structs that never expose tokens.
<br/>
---
## 🌐 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.
<br/>
---
## 📊 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:
```bash
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**
<br/>
---
## 🛠️ 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. |
<br/>
---
## 🚀 Quick Start
### 1. Headless NPM CLI (Zero Setup)
Instantly auto-configure your AI tools in 1 second:
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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**:
```bash
npm run demo
```
<br/>
---
## 🛡️ 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`:
```json
{
"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
}
```
<br/>
---
## 🏗️ 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 │ │ │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
```
<br/>
---
## 📄 License
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.
<div align="center">
**Built with 🖤 by [RABNEER](https://github.com/RABNEER) & The AgentBox Open Source Community**
</div>
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues