Axocoatl

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

Kill the server mid-task — the agent restarts from its last checkpoint, not from zero. 100% local.

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, OpenRouter. 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.

Roadmap

Built and tested in the axocoatl-coordination crate, but not yet wired into
the shipped runtime:

• HTN symbolic planning — task decomposition without LLM calls.
• Auction-based agent selection — pick agents by tool capability, load, and
  remaining token budget.
• Stronger sandbox isolation tiers — the shipped sandbox is a hardened
  rootless Podman container (capabilities dropped, no-new-privileges,
  network-isolatable); microVM-class isolation (Firecracker) is planned.

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         # 340+ tests

License

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