Skip to content
Axocoatl

Getting started

This is the 5-minute path from “nothing installed” to “a workflow ran on my box.” If anything breaks, see Troubleshooting.

Prerequisites

Section titled “Prerequisites”
  • macOS or Linux (x86_64 or aarch64). On Windows, run Axocoatl inside WSL2 — see Windows (WSL2) below.
  • Ollama for local LLM use (recommended for first contact). Five other providers work too — OpenAI, Anthropic, Mistral, Gemini, and OpenRouter; set the right key in .env. (The openai provider also takes a base_url, so it targets any OpenAI-compatible endpoint — LM Studio, vLLM, MLX, and the like.)
  • (Optional) podman if you want sandboxed directory sessions.

  1. Install Axocoatl.

    Terminal window
    curl -fsSL https://axocoatl.ai/install.sh | sh

  2. Pull a model.

    Terminal window
    ollama serve &
    ollama pull llama3.2

  3. Run axocoatl doctor to confirm everything is reachable.

    Terminal window
    axocoatl doctor

    You should see ✓ on Rust toolchain, config, Ollama, model, data dir, and (if installed) podman.

  4. Start the daemon.

    Terminal window
    axocoatl dev

    This brings up the daemon, IPC, and the dashboard on http://localhost:8080.

  5. Open the dashboard and fire a workflow.

    In your browser, open http://localhost:8080. Switch to Studio. In the left rail, expand Quick fire and click ▶ Fire all workflows. Watch the lattice cascade through every agent on the canvas.

Windows (WSL2)

Section titled “Windows (WSL2)”

Axocoatl is a Unix-first runtime — the session sandbox is rootless Podman and the always-on service is systemd/launchd — so on Windows it runs inside WSL2, not natively. There is no native Windows binary; the install script above will point you here if you run it from PowerShell or Git Bash.

  1. Install WSL2. In an administrator PowerShell, then reboot when prompted (this installs Ubuntu by default):

    Terminal window
    wsl --install

  2. Open your WSL distro and install Podman (needed for sandboxed directory sessions):

    Terminal window
    sudo apt-get update && sudo apt-get install -y podman

  3. Install Axocoatl inside WSL — the same one-liner, now detected as Linux:

    Terminal window
    curl -fsSL https://axocoatl.ai/install.sh | sh

  4. Run it. axocoatl dev inside WSL, then open http://localhost:8080 in your Windows browser — WSL2 forwards localhost to the host automatically.

For the always-on service (axocoatl service install), enable systemd in WSL2: add a [boot] section with systemd=true to /etc/wsl.conf, then run wsl --shutdown once from PowerShell. Plain axocoatl dev does not need it.

What just happened?

Section titled “What just happened?”

The daemon spawned a supervised actor for every agent in your config. The lattice published a WorkflowStarted event. Every agent that lists the workflow’s entry point in its depends_on chain woke up and ran. Their outputs published TaskCompleted events; downstream agents activated as their thresholds were crossed. Nobody scheduled anything.

Open a directory session to see the agent actually read, write, and execute commands inside a sandboxed copy of one of your folders.

Next

Section titled “Next”
  • The event lattice — the coordination model.
  • Agents — actor lifecycle, supervision, budgets.
  • Skills — how the lattice routes work automatically.
  • Sessions — Claude-Code-style directory work, locally.