allman

Allman

A high-performance MCP agent mail server built in Rust. Named in honor of Eric Allman, creator of Sendmail.

Allman acts as the communication backbone for large swarms of autonomous AI agents — concurrent durable message routing, near-real-time search, and a Git-backed profile audit trail, all exposed through the Model Context Protocol.

Architecture

[ Agent Swarm ]                      [ vLLM / GPU Inference ]
       |                                   (Port 8001)
  MCP JSON-RPC                              |
       v                                    |
+----------------------------------------------+
|              ALLMAN SERVER (Rust)              |
|                                               |
|  MCP Controller   (tools/call, tools/list)    |
|       |                                       |
|  PostOffice                                   |
|    ├─ DashMap        recoverable hot projection|
|    ├─ Fjall          durable message log       |
|    ├─ Tantivy        NRT full-text search      |
|    └─ Git Actor      profile audit trail       |
|                                               |
|  Persist Worker      batched indexing pipeline  |
|    crossbeam-channel → Tantivy IndexWriter     |
+----------------------------------------------+
              Port 8000

Hot path: validation and reads remain in memory. Message writes pass through a dedicated Fjall group-commit actor and are acknowledged only after the configured durability boundary.

Persistence: canonical messages and per-recipient delivery pointers are stored atomically. DashMap inboxes and the Tantivy index are rebuildable projections. A 350µs microbatch window amortizes sync cost across concurrent sends.

MCP Tools

Connect any MCP-compatible client to http://localhost:8000/mcp.

Tool	Description
create_agent	Register an agent (project_key, name_hint, program, model)
send_message	Send a message (from_agent, to, subject, body, project_id)
get_inbox	Retrieve and drain unread messages for an agent
receive_messages	Lease unread messages with a visibility timeout
ack_messages	Durably acknowledge a leased batch
search_messages	Full-text search across all indexed messages

Getting Started

Prerequisites

• Rust 1.90+
• Docker (optional — for containerized deployment and vLLM)
• NVIDIA GPU + nvidia-container-toolkit (optional — only for LLM inference)

Build from Source

git clone https://github.com/copyleftdev/allman.git
cd allman
cargo build --release

Run

# Start the server (binds to 0.0.0.0:8000)
cargo run --release

Configuration via environment variables (or .env):

Variable	Default	Description
INDEX_PATH	allman_index	Tantivy index directory
REPO_ROOT	allman_repo	Git audit trail directory
STORE_PATH	allman_store	Fjall durable message store directory
DURABILITY_MODE	strict	strict, balanced, or buffered
SERVER_ADDR	0.0.0.0:8000	HTTP listen address
RUST_LOG	allman=debug	Log level filter

strict uses fsync, balanced uses fdatasync, and buffered protects against process crashes but not OS or power loss. Production deployments should use strict unless their filesystem guarantees make balanced appropriate.

Docker

# Allman server only
docker compose up allman -d

# Allman + vLLM GPU inference
sudo ./setup_gpu.sh   # one-time NVIDIA toolkit install
docker compose up -d

Simulations

Included binaries demonstrate swarm behavior with LLM-driven agents:

Binary	Description
cyber_sim	30-agent cybersecurity incident response (Blue Team, Forensics, CISO)
black_friday	Retail chaos simulation with personality-driven personas
escrow_sim	Real estate closing day with buyer, seller, and escrow officer
swarm_stress	High-concurrency stress test for throughput benchmarking
benchmark	Targeted latency and throughput measurements

cargo run --release --bin cyber_sim
cargo run --release --bin swarm_stress

Note: Simulations that use LLM inference require a running vLLM instance on port 8001. The stress test and benchmark run against Allman alone.

Project Structure

src/
├── main.rs           Axum server, routing, MCP endpoint
├── controllers.rs    MCP tool dispatch (create_agent, send_message, etc.)
├── durable.rs        Fjall group-commit actor, recovery, leases, acknowledgements
├── state.rs          PostOffice: DashMap state, Tantivy index, persist pipeline
├── models.rs         Data types (InboxEntry, Agent, Message)
├── git_actor.rs      Dedicated OS thread for Git audit commits
└── bin/
    ├── benchmark.rs
    ├── black_friday.rs
    ├── cyber_sim.rs
    ├── escrow_sim.rs
    ├── simulation.rs
    └── swarm_stress.rs

Contributing

cargo fmt
cargo check   # must pass clean
cargo test

License

MIT