# Axocoatl
**The Rust runtime for self-coordinating multi-agent systems.**
[](https://github.com/axocoatl/axocoatl/actions/workflows/ci.yml)
[](https://crates.io/crates/axocoatl-cli)
[](LICENSE)
<p align="center">
<img src="docs/img/demo.gif" alt="Axocoatl crash-restart — kill the server mid-run and the agent resumes from its last checkpoint, fully local" width="760">
</p>
<p align="center"><em>Kill the server mid-task — the agent restarts from its last checkpoint, not from zero. 100% local.</em></p>
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
```bash
# 1. Install (no Rust toolchain required)
# 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`](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
| Language / runtime | Rust / actors | Rust / actors | Python |
| **Stigmergic coordination** (no orchestrator) | ✅ | ❌ | ❌ |
| HTN symbolic planning | ✅ | ❌ | ❌ |
| Auction-based agent selection | ✅ | ❌ | ❌ |
| Per-agent token budgets | ✅ | ❌ | partial |
| 4-tier persistent memory + checkpointing | ✅ | partial | partial |
| MCP client + server | ✅ | partial | ✅ |
| A2A protocol | ✅ | ❌ | ❌ |
| Provider-agnostic (Ollama/OpenAI/Anthropic/…) | ✅ | ✅ | ✅ |
| Interactive onboarding + `doctor` | ✅ | ❌ | ❌ |
The differentiator is the **coordination layer**: define agents with
`depends_on`, and the event lattice cascades work through them automatically.
```yaml
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
```
```bash
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.
- **Hybrid memory recall** — relevant past exchanges are injected each turn, and
the agent can also pull on demand: `recall_search` (semantic search over past
sessions) and `recall_timeframe` (read a day's activity log). Tunable per agent.
- **Agent-managed core memory** — editable blocks (`persona`, `human`, `project`,
…) the agent curates via tools and that render into its prompt each turn (the
MemGPT/Letta model). Per-agent by default, shareable across agents. A
background "sleep-time" pass consolidates idle agents' memory automatically.
- **Stigmergic coordination** — agents publish `TaskCompleted` events; an
`EventLattice` accumulates pheromone signals and activates downstream agents
when thresholds are crossed. No scheduler, no glue code.
- **Coordinator role** — for explicit hierarchical work, an agent with
`role: coordinator` decomposes a goal into subtasks (HTN or LLM), auctions them
to worker agents, runs them in parallel, and synthesizes the results. The pass
is resumable via checkpointing.
- **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](https://docs.axocoatl.ai) for the full picture, the
[marketing site](https://axocoatl.ai) for the positioning, or
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and
[`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) for the in-repo
quick reference.
---
## Roadmap
- **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 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/`](examples/):
`research-assistant`, `code-reviewer`, `customer-support`.
## Build from source
```bash
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](LICENSE). Changes: [CHANGELOG.md](CHANGELOG.md).