# GenSwarms

> The operating system for AI workforces. You declare the agents, deterministic objects, backends, and the directed message graph that connects them; GenSwarms runs each agent as a separate, supervised process, streams every event live, and restarts failures automatically.

- **Processes** — every agent and object runs as a supervised OTP process; a crashed agent restarts without stopping the others. An agent's role, model and backend are set separately; agent groups scale up and down while the swarm runs.
- **Isolation** — per-agent sandbox: bwrap namespaces with a copy-on-write root and seccomp, or Docker / Apple container.
- **Network** — with `network: :isolated` an agent reaches its model endpoint and nothing else (bwrap and Docker).
- **Messages** — a declared directed topology is the only way messages move; every hop is checked against it and off-graph messages are dropped.
- **Services** — objects: deterministic Elixir handlers on the same graph as agents (for example a Telegram gateway, a cron scheduler, a browser, per-conversation LLM budgets).
- **Drivers** — 7 backends: Local, Tmux (Codex, Claude Code and OpenCode sessions), Docker, Apple container, SSH, Bwrap, Mock.
- **Packages** — `gsp` and the `swarmidx` notary: signed, content-addressed packages, verified on your machine against a transparency log.
- **State** — a swarm is a seed plus an ordered log of changes; the gate checks the whole configuration and every change before it runs and refuses a bad one; a stopped swarm restores from its database.
- **Control** — a REST API, a WebSocket, a CLI, and a skill file (skill.md) for coding agents.
- **Events** — one event stream: every message, crash, restart and output, live over WebSocket.

Current version: 0.2.0. License: MIT.
Language versions of this page: English https://genswarms.com/, Español https://genswarms.com/es/, 한국어 https://genswarms.com/ko/, 简体中文 https://genswarms.com/zh/, Русский https://genswarms.com/ru/, Türkçe https://genswarms.com/tr/.

## Start here

- [Operating skill (SKILL.md)](https://genswarms.com/skill.md): the canonical, agent-readable how-to for installing, configuring, and running a swarm. Point your coding agent at this.
- [Getting started](https://genswarms.com/docs/getting-started/): install, build the `genswarms` CLI, run your first swarm, environment variables.

## Documentation

- [Configuration](https://genswarms.com/docs/configuration/): the swarm config DSL — agents, objects, topology, and backends (`.exs`/`.json`/`.yaml`).
- [CLI reference](https://genswarms.com/docs/cli/): every `genswarms` / `mix genswarms.*` command with flags.
- [Architecture](https://genswarms.com/docs/architecture/): supervision tree, the daemon model, and deployment topologies.
- [Messaging & routing](https://genswarms.com/docs/messaging/): `@agent:` syntax, topology-gated routing, file inbox/outbox.
- [Objects](https://genswarms.com/docs/objects/): deterministic, non-agentic components that participate in the topology.
- [Skills](https://genswarms.com/docs/skills/): per-agent markdown skills and template variables.
- [Backends](https://genswarms.com/docs/backends/): Local, Tmux, Docker, Apple container, SSH, Bwrap, and Mock execution backends.
- [Containers](https://genswarms.com/docs/containers/): NixOS container images, tool presets, and sandbox internals.
- [REST API](https://genswarms.com/docs/rest-api/): the complete JSON HTTP API.
- [WebSocket API](https://genswarms.com/docs/websocket/): real-time agent output, routing, and event streams.
- [Programmatic usage](https://genswarms.com/docs/programmatic/): driving GenSwarms as an Elixir library.
- [Observability](https://genswarms.com/docs/observability/): logs, events, and metrics.
- [Testing](https://genswarms.com/docs/testing/): validating and running swarms, the mock backend.
- [Troubleshooting](https://genswarms.com/docs/troubleshooting/): common issues and fixes.

## More

- [Blog](https://genswarms.com/docs/blog/): notes and guides from the team building GenSwarms.
- [Full documentation (single file)](https://genswarms.com/llms-full.txt): every doc page concatenated for one-shot ingestion.
- [GitHub repository](https://github.com/genlayerlabs/genswarms): source, issues, and license.
- [SubZeroClaw](https://github.com/genlayerlabs/subzeroclaw): the minimal open-source agent loop Tmux workers run by default (they can also run Codex, Claude Code or OpenCode).