Operating Swarm

Open Swarm

Brand marks live under [assets/brand/](assets/brand/): minimal for the tab favicon and PWA icons, geometric for in-app WebUI chrome, and cyber-swarm for marketing / website fanfare (#768).

Open Swarm is a Grok-like WebUI and an OpenAI-compatible API that seats four kinds of agents — CLI, API (true inference), Blueprint (programmatic / openai-agents), and Remote (Hermes / OpenMousBot / Rakazo / Herdr) — and composes them with handoff and agent-as-tool. The same blueprint runs from swarm-cli and from /v1/chat/completions.

WebUI is first-class: left rail + the selected agent’s chat. Other clients (SDK, curl, Open WebUI, and swarm-cli tui — the interactive terminal client of that same API, REQ-111) hit the same seats at /v1/chat/completions and /v1/responses. swarm-cli tui opens an AGENTS rail + live chat (hydrate, send + stream, sessions) over the WebUI’s REST + SSE. Every client is one API — no second runtime, no remote Herdr SSH.

AI enthusiasts juggle many frameworks; some combine CLIs and APIs, but still do not talk to remote harnesses (Hermes, OpenMousBot as remote, …). Open Swarm is a Grok-agnostic Grok-Bot-like UI and a bridge — task one place, coordinate across CLI, API, remotes, and local blueprints.

Announce copy, storyboard, and recapture checklist: [docs/ANNOUNCE.md](docs/ANNOUNCE.md) (REQ-136 / #529). Asset path for this hero and the later CLI / API / remotes / combined kit: [docs/assets/readme/](docs/assets/readme/README.md) (#456).

Direction: [docs/VISION.md](docs/VISION.md). Vocabulary: [docs/GLOSSARY.md](docs/GLOSSARY.md).

Demos

Compact walkthroughs of open-swarm's core agent capabilities — from individual CLI, API, and Remote seats to a unified team combining all three in one flow.

| Kind / Story | What it demonstrates | Preview | |---|---|---| | CLI Agent | Host executable running in a native terminal session (grok, agy, opencode) | | | API Agent | True inference seat queried directly via the OpenAI-compatible HTTP completions API | | | Remote Agent | External agentic harnesses (OpenMousBot, Hermes, Rakazo, Herdr) | | | Combined Team | The open-swarm differentiator: one flow coordinating CLI + API + Remote via openai-agents handoff | |

> A historical terminal loop (one blueprint as CLI + API) is preserved at [docs/demo/cli-and-api.gif](docs/demo/cli-and-api.gif).

---

WebUI (start here)

Product chrome is the Grok-like SPA: rail, remotes, sessions, Settings sheet. / and /chat are that chrome. Django trailing-slash pages (/blueprint-library/, /settings/, /sessions/, …) stay the operator dump — not the pitch.

git clone https://github.com/matthewhand/open-swarm.git
cd open-swarm
uv sync --all-extras
cp .env.example .env          # set OPENAI_API_KEY, API_AUTH_TOKEN, DJANGO_SECRET_KEY
cp swarm_config.example.json swarm_config.json   # optional local SoT; secrets stay ${VAR} in .env
make frontend                 # builds webui/frontend/dist/
docker compose up --build     # API + local Postgres (not Neon / not SQLite)
# open http://localhost:8000   # greenfield compose/swarm-api default

> Ports: On a standard docker compose / swarm-api setup, the Open Swarm ASGI + WebUI listen on :8000. If an upstream LLM gateway or proxy already binds :8000, Open Swarm can be run on an alternate port (such as :8002). Ensure client API and session calls target the Open Swarm server port. For configuration details, see [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

Compose’s durable DB is the postgres service. Set DATABASE_URL for any cloud Postgres. Neon is test/CI only — [docs/DATABASE.md](docs/DATABASE.md).

Without dist/, / falls back to Django templates. Rebuild after SPA pulls. Auth: [docs/AUTH.md](docs/AUTH.md) (websocket needs a session cookie; bearer does not auth WS).

---

Short history

• 2024-12 — Started as a derivative of OpenAI’s experimental Swarm; Django REST API the same week.
• 2026-02 — First git tag 0.0.1 (no GitHub Release, no PyPI 0.0.1).
• 2026-04 — React Web UI.
• 2026-06 — MoA, CLI fusion, /v1/responses. Last published cut: v0.5.4 (2026-06-19). PyPI summary still says “Orchestrating AI Agent Swarms with Django.”
• 2026-07+ — Remotes, Team handoff rosters, Herdr, Grok-like WebUI chrome — on main, not in 0.5.4.
• 2026-09 — Kinds lock: CLI | API | Blueprint | Remote. Team = Blueprint subtype. WebUI first-class. Built on the openai-agents SDK.

---

Kinds (locked)

Four user-facing kinds. Team is not a fifth kind.

| Kind | Meaning | |---|---| | CLI | Host executable (grok, agy, claude, gemini, opencode, …). Native session. | | API | True inference seat — OpenAI-compatible chat completions (base URL / model / key-env). Not a graph. | | Blueprint | Programmatic recipe — openai-agents handoffs, MoA, custom Python. May use inference underneath; the seat is the recipe. Same id via CLI and API only — blueprints do not ship a webpage. The Grok-like WebUI is the product chrome. | | Remote | Another agentic harness. Implementations: Hermes, OpenMousBot, Rakazo, Herdr (and nested Open Swarm). Variants are adapters, not extra kinds. Herdr is SSH-shaped, not another HTTP remote. |

Team = a Blueprint subtype: a roster plus openai-agents handoff / agent-as-tool so CLI, API, Blueprint, and Remote members can see and talk. Do not call /v1/teams aliases a Team — those are Profiles (LLM-profile aliases).

Honest mid-flight (#652 / [ADR-006](docs/adr/006-api-vs-blueprint-kinds.md)): on main today, stored api is still the leftover “not CLI, not remote” bucket (mostly recipes). There is not yet a first-class “wire this endpoint” seat. Target: rename those seats to blueprint, then introduce a true api inference seat. Prefer the four names above in new copy.

---

Why openai-agents

The differentiator is a programmatic graph — not “let chat figure it out,” and not “many concurrent seats” (Grok Bot / Rakazo / OpenMousBot). openai-agents handoff / agent-as-tool can enforce a forced BA → Engineer → Tester sequence, or a circular Skeptic punt-back.

Limit (up front): that graph runs inside Blueprint seats (today’s leftover api bucket). We cannot inject openai-agents into CLI or Remote harnesses — those stay native sessions. Cross-kind teams still work: a Blueprint coordinator can sit with a Grok CLI and a Hermes Remote.

Two ways to build a team

Under the hood a team/workflow is a Python blueprint class ([ADR-005](docs/adr/005-kind-bases.md)). That is the power-user path.

Happy path: ask Support in natural language — “Create a BA → Engineer → Tester workflow.” Support persists a usable seat. You do not write Python. Code stays hidden unless you choose View / edit code. The product bootstraps more of itself this way (REQ-158 / #567). Guided path + checklist (GitHub-only): [docs/SUPPORTNLBLUEPRINTS.md](docs/SUPPORTNLBLUEPRINTS.md).

Mermaid, kind bases, and the :8001 seed live on [docs/DEVELOPER.md](docs/DEVELOPER.md). Worked configs: [docs/examples/openai-agents-handoff-graphs/](docs/examples/openai-agents-handoff-graphs/README.md) (REQ-156 / #564). Demo roster names (Mode A kind-clear vs Mode B personas): [docs/SHOWOFFDEMOAGENTS.md](docs/SHOWOFFDEMOAGENTS.md) (REQ-135 / #526). Kind-base ADR: [ADR-005](docs/adr/005-kind-bases.md) (REQ-159 / #570).

---

Install (version honesty)

| Source | Fact | |---|---| | main (this repo) | Current product: WebUI chrome, remotes, Team rosters, four-kind lock. Prefer clone. | | PyPI open-swarm | Latest 0.5.4 (2026-06-19). Same as GitHub Release v0.5.4. | | PyPI / pyproject.toml summary | Still “Orchestrating AI Agent Swarms with Django.” Classifier is Alpha. That published wheel does not include Grok chrome, remotes catalog, or combined-team work landed after June. | | GitHub Release title | v0.5.4 — django_chat resolves its LLM profile — historical; not the 2026-09 pitch. |

# What main actually runs
git clone https://github.com/matthewhand/open-swarm.git
cd open-swarm
uv sync --all-extras

pip install open-swarm is the June 2026 cut. Do not expect this README’s kinds or WebUI from that wheel.

Python >= 3.10. Node >= 22 only if you build the WebUI.

---

Run from the operator CLI / API

export OPENAI_API_KEY="sk-..."

# CLI kind — discover installed agentic CLIs
uv run swarm-cli cli-agents --init --write --check-auth
uv run swarm-cli launch cli_agent --message "What CLIs can you see?"

# Blueprint kind — same recipe as an OpenAI `model` id
uv run swarm-cli launch codey --message "Explain this repo's structure"

# Remote kind — fresh install catalog is empty until Settings +Add (OpenMousBot / Hermes / Rakazo / Herdr).
# A populated live host may already list remotes; tip defaults stay empty-until-Add.
uv run swarm-cli remotes
# uv run swarm-cli remotes place 

# OpenAI-compatible door (after the WebUI / compose steps above).
# Standard compose/swarm-api listens on :8000.
curl -sf http://localhost:8000/v1/models | jq .
curl -sf http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_AUTH_TOKEN}" \
  -d '{"model": "cli_agent", "messages": [{"role":"user","content":"ping"}]}' | jq .

model selects which seat / recipe handles the request. Streaming is supported. Full CLI reference: [USERGUIDE.md](./USERGUIDE.md). Remotes: [docs/REMOTEHARNESSES.md](docs/REMOTEHARNESSES.md). Herdr: [docs/HERDR.md](docs/HERDR.md). CLI wrap / fusion (not the first team story): [docs/CLIFUSION.md](docs/CLIFUSION.md). MoA consensus (not the first team story): [docs/MOA.md](docs/MOA.md).

Pinokio (local sideload)

Open Swarm is not in the Pinokio public catalog. In Pinokio, add the git URL only (Download from URL / sideload) — do not search Discover:

https://github.com/matthewhand/open-swarm.git

Then Install → Start → Open App. Compose sets SWARM_RUNTIME=sandbox-home (REQ-45). Pinokio requires root pinokio.js; install/start/update scripts live under pinokio/.

---

Links

• [docs/ANNOUNCE.md](docs/ANNOUNCE.md) — launch spiel + hero GIF (REQ-136 / #529)
• [docs/VISION.md](docs/VISION.md) — where we are going (kinds, WebUI, remotes)
• [docs/GLOSSARY.md](docs/GLOSSARY.md) — kinds, Team vs Profiles vs roster
• [USERGUIDE.md](./USERGUIDE.md) — swarm-cli tasks
• [docs/REMOTEHARNESSES.md](docs/REMOTEHARNESSES.md) · [docs/HERDR.md](docs/HERDR.md)
• [docs/AUTH.md](docs/AUTH.md) · [CONFIGURATION.md](./CONFIGURATION.md) (swarm_config.example.json)
• [FEATURESTATUS.md](./FEATURESTATUS.md) · [ROADMAP.md](./ROADMAP.md)
• [docs/DEVELOPER.md](docs/DEVELOPER.md) — gateway, /v1/responses, dated history, contribution pointers
• [docs/diagrams/](docs/diagrams/README.md) — visual architecture stack, taxonomy tree, lifecycle state machine, and delegation sequence diagrams
• [CONTRIBUTING.md](./CONTRIBUTING.md)

Recipes and pattern diagrams stay in [docs/EXAMPLES.md](docs/EXAMPLES.md) and [docs/ORCHESTRATIONPATTERNS.md](docs/ORCHESTRATIONPATTERNS.md) — they are not the front door.

---

Status

Alpha (pyproject.toml / PyPI classifier). main is ahead of published 0.5.4. Core CLI, OpenAI-compatible API, websocket chat, and the Grok-like WebUI are working and covered by keyless pytest plus frontend unit tests. Honest gaps (true API inference seat, live mem0, MCP server mode, desktop installer): [FEATURESTATUS.md](./FEATURESTATUS.md).

Acknowledgements

Open Swarm began as an extension of OpenAI’s experimental Swarm and migrated to the openai-agents SDK for agents, tools, and handoffs.

License

MIT — see [LICENSE](LICENSE). Attribution and vendored-asset notices live in [NOTICE](NOTICE).

Contributing

Issues and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/DEVELOPER.md](docs/DEVELOPER.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: matthewhand
• Source: matthewhand/operating-swarm
• License: MIT

Install and usage instructions live in the source repository linked above.