genswarms-use

name

genswarms-use

description

Drive genswarms — the Elixir/OTP orchestrator for swarms of subzeroclaw agents. Load this to define a swarm (agents + objects + topology), run it as a daemon, and observe/scale/message it via the `genswarms` CLI or the REST + WebSocket API. Orients and points into the root SKILL.md (operating-genswarms) and docs/ for depth. To develop or extend genswarms itself (add a backend or object, touch the IR/API/daemon), use genswarms-contribute.

Using genswarms

A swarm is a declarative set of agents (each an execution backend + skills + model), optional non-agentic objects (deterministic Elixir components in the graph), and a directed topology connecting them. Swarms run as independent daemon OS processes; the CLI, the optional Phoenix API, and the daemons coordinate through SQLite at .genswarms/swarms.db. This skill is the orientation; the root SKILL.md (operating-genswarms) is the full operating guide and docs/ carries every topic.

Define a swarm

A config file (.exs / .json / .yaml) with required name: and agents:, plus optional objects:, topology:, skills_base_dir:. Each agent carries three orthogonal slots — body (skills/persona), model (LLM), backend (execution env). See docs/configuration.md and docs/getting-started.md. Under the hood a config is translated to the IR swarm.state and validated before anything spawns (see genswarms-contribute / docs/intermediate-representation.md).

Drive it — the CLI

Build the escript once (mix escript.build → ./genswarms), then:

genswarms start <config>      start a swarm as a daemon
genswarms status [name]       lifecycle + agent state
genswarms task <name> …       send a task into the swarm
genswarms msg  <name> …       send a message to an agent
genswarms logs / events       stream logs / the event log
genswarms scale <name> …      grow/shrink an agent group live
genswarms overlay / snapshot  inspect/mutate the running swarm's IR
genswarms stop | restart      lifecycle
genswarms list-skills | build | config | check | init | dashboard(up)/down | env

Entry point: Genswarms.CLI.main/1 (lib/genswarms/cli.ex). A few operations are Mix-task-only (not on the escript): mix genswarms.pause, resume, delete, clean, restart_agent. Full reference: docs/cli.md.

Drive it — the API

Optional Phoenix server (mix phx.server, default :4000, PORT to change):

• REST /api/*: swarms (list/create/detail/stop), per-agent ops (task, restart, logs, history, skills), dynamic topology, objects, overlay/snapshot, messages/events, skills, config/validate. See docs/rest-api.md.
• WebSocket channel swarm:{name} at /swarm/websocket: inbound send_task / get_status / subscribe_logs / subscribe_events; outbound agent_output, message_routed, agent_status, topology_changed, log_entry, event, … See docs/websocket.md.
• Auth: Bearer GENSWARMS_API_TOKEN. If unset, the server is loopback-only by default (docs/security.md).

Backends & isolation

An agent's backend is where it runs: :local (Port subprocess), :docker (NixOS container), :apple_container, :ssh, :bwrap (bubblewrap sandbox), :mock (no LLM, for tests). Add network: :isolated to run an agent that ingests untrusted content with no network except a forwarder pinned to the LLM — so a prompt-injected agent can't reach the orchestrator or exfiltrate (bwrap and docker support it; Apple container rejects it). See docs/backends.md, docs/containers.md, docs/security.md.

Gotchas

• The model rides through to subzeroclaw. Agents are subzeroclaw processes; their routing/model is configured per the subzeroclaw contract (request_extra etc.) — see the subzeroclaw-use skill.
• Container presets vs the build allowlist don't match today. The real Nix presets are base, code, data, node, python, web (nix/tool-presets.nix), built via nix build .#agentContainer-<preset>. The genswarms build command's own allowlist (@available_images in lib/mix/tasks/genswarms/build.ex, mirrored in docs/cli.md) currently lists base, python, node, elixir — so elixir isn't a real preset and code/data/web aren't reachable through the command. Prefer the nix build form until this is reconciled.
• Loopback by default. Without GENSWARMS_API_TOKEN the API refuses non-loopback callers — set the token before exposing it.
• Mock without LLM: backend: :mock spawns nothing; for a real agent loop without spending, set SUBZEROCLAW_MOCK_SCRIPT.

Where to read more

• Root SKILL.md (operating-genswarms) — the full operate-a-swarm guide.
• docs/getting-started.md, docs/cli.md, docs/configuration.md — define + run.
• docs/rest-api.md, docs/websocket.md, docs/programmatic.md — drive over HTTP/WS.
• docs/backends.md, docs/containers.md, docs/security.md — execution + isolation.
• docs/observability.md, docs/messaging.md, docs/objects.md — watch + wire.