Skip to content

Genswarms documentation

Genswarms is an Elixir/OTP orchestrator for swarms of subzeroclaw agents, with pluggable backends, arbitrary directed-graph topologies, per-agent skills, and fault tolerance via OTP supervision trees.

This is the documentation index. If you are new, start with Getting started and work through the area you need.

Entry points

  • README.md (repo root) — project overview and quick start.
  • SKILL.md (repo root) — the how-to-operate quick path for driving swarms via the genswarms CLI and REST API.
  • Getting started — the full first-swarm walkthrough.

Getting started

  • Getting started — install, build the genswarms CLI, run your first swarm, and the key environment variables.
  • Configuration — the swarm config DSL: agents, objects, topology, backends, and the .exs / .json / .yaml formats.
  • CLI reference — every genswarms / mix genswarms.* command with its flags and examples.

Operating

  • Messaging — the @agent: syntax, topology-gated routing, file inbox/outbox, and the swarm-msg helper.
  • Skills — per-agent markdown skills and the {{agent_name}} / {{swarm_name}} / {{workspace}} template variables.
  • Objects — non-agentic Elixir components that participate in the topology and run deterministic code.
  • Observability — the event spine: events, logging, telemetry, and streaming.
  • Testing and development — ExUnit unit tests, the e2e harness (mix genswarms.test), and the Mock backend.
  • Troubleshooting — common problems with startup, routing, backends, tasks, and the API server.

Architecture and internals

  • Architecture — the OTP supervision tree, the daemon model, and supported deployment topologies.
  • Backends — the Local, Docker, SSH, Bwrap, and Mock execution backends and the shared backend contract.
  • Containers and sandboxes — NixOS container images, tool presets, and the bwrap sandbox internals.

Reference

  • REST API — the complete pure-JSON HTTP API served by Phoenix.
  • WebSocket API — real-time agent output, message routing, and event streams over the swarm:{name} channel.
  • Programmatic API — driving Genswarms directly as an Elixir library.