Axocoatl

The Rust runtime for self-coordinating multi-agent systems.

Axocoatl runs persistent AI agents that coordinate through a stigmergic event lattice — agents activate when their dependencies complete, driven by pheromone-style signals with no central orchestrator. Built in Rust on the ractor actor model: low memory, fast cold start, provider-agnostic.

60-second quickstart

# 1. Install (no Rust toolchain required)
curl -fsSL https://raw.githubusercontent.com/axocoatl/axocoatl/main/scripts/install.sh | sh

# 2. Interactive setup wizard — picks a provider, scaffolds a project
axocoatl onboard

# 3. Check your environment
axocoatl doctor

# 4. Start the daemon + API, then chat
axocoatl dev
axocoatl chat -a assistant

Prefer Cargo? cargo install axocoatl-cli (requires Rust 1.82+).

Skipping onboard? Copy axocoatl.example.yaml to axocoatl.yaml — two agents and one workflow, fits on one screen. The full axocoatl.yaml shipped in the repo is the larger demo (12 agents, scheduled runs, MCP servers).

Why Axocoatl

The differentiator is the coordination layer: define agents with depends_on, and the event lattice cascades work through them automatically.

agents:
  - id: researcher
    provider: ollama
    model: llama3.2
    depends_on: []
  - id: summarizer
    provider: ollama
    model: llama3.2
    depends_on: [researcher]   # activates when researcher completes

workflows:
  - id: research-and-summarize
    agents: [researcher, summarizer]
    entry_point: researcher

axocoatl workflow run research-and-summarize -i "What is photosynthesis?"

Core concepts

• Agents — persistent ractor actors with a provider, tools, 4-tier memory, and a token budget. Survive restarts via checkpointing.
• Stigmergic coordination — agents publish TaskCompleted events; an EventLattice accumulates pheromone signals and activates downstream agents when thresholds are crossed. No scheduler, no glue code.
• Workflows — declarative multi-agent DAGs via depends_on / entry_point.
• Providers — Ollama, OpenAI, Anthropic, Mistral, Gemini. No lock-in.
• Protocols — MCP (consume & expose tools) and A2A (agent interop).

See the docs site for the full picture, the marketing site for the positioning, or docs/ARCHITECTURE.md and docs/TROUBLESHOOTING.md for the in-repo quick reference.

CLI

axocoatl onboard                 Interactive setup wizard
axocoatl doctor                  Environment / dependency health check
axocoatl init <name>             Scaffold a project non-interactively
axocoatl validate <config>       Validate a config file
axocoatl dev | serve             Run daemon (+ IPC) / production server
axocoatl chat -a <agent>         Interactive chat
axocoatl workflow list | run     Inspect / execute multi-agent workflows
axocoatl agents list|status|restart
axocoatl tokens report           Per-agent token usage
axocoatl mcp servers|tools       Inspect connected MCP servers/tools

HTTP API

GET  /health                          POST /api/agents/{id}/execute
GET  /api/agents                       GET  /api/agents/{id}/status
POST /api/agents/{id}/restart          GET  /api/tokens/report
GET  /api/workflows                    POST /api/workflows/{id}/execute
GET  /api/mcp/servers                  GET  /api/mcp/tools
GET  /ws   (WebSocket streaming)

Examples

Runnable, mock-LLM (no keys needed) — see examples/: research-assistant, code-reviewer, customer-support.

Build from source

git clone https://github.com/axocoatl/axocoatl
cd axocoatl
cargo build --release          # binary: target/release/axocoatl
cargo test --workspace         # 318+ tests

License

Apache-2.0 — see LICENSE. Changes: CHANGELOG.md.