Treat external harnesses and peer instances as one common abstraction.
Operating Swarm (OS) is a provider-agnostic agent operating layer and harness. It runs its own native agentic execution (os-core), connects to external harnesses (os-adapter-hermes, os-adapter-truforge), and peers with other Operating Swarm instances (os-peer). Sessions persist while switching providers, harnesses, or OS nodes. OS is not only a UI, wrapper, gateway, adapter, or supervisor.
Three interfaces sit on that core: OS WebUI (os-webui), OS CLI (os-cli, shortcut os), and the OpenAI-compatible OS API (os-api). A fourth, optional surface is the desktop tray os-marchy-systray — it lists your bots grouped by rig/team and connects to a local OS (auto-detected) or a remote instance (#1306). Umbrella repository: operating-swarm. Python import path remains swarm.
It seats four kinds of agents — CLI, API (true inference), Blueprint (programmatic / openai-agents), and Remote — and composes them with handoff and agent-as-tool. The same blueprint runs from os-cli and from /v1/chat/completions.
WebUI is first-class: left rail + the selected agent’s chat. Other clients (SDK, curl, Open WebUI, and os-cli tui — the interactive terminal client of that same API, REQ-111) hit the same seats at /v1/chat/completions and /v1/responses.
Brand marks live under assets/brand/: minimal for the tab favicon and PWA icons, geometric for in-app WebUI chrome, and cyber-swarm for marketing / website fanfare (#768).
Announce copy, storyboard, and recapture checklist: docs/ANNOUNCE.md (REQ-136 / #529) — Grok-agnostic chrome plus a CLI/API/remote harness bridge. Asset path for this hero and the later CLI / API / remotes / combined kit: docs/assets/readme/ (#456).
Direction: docs/VISION.md. Vocabulary: docs/GLOSSARY.md.
Compact walkthroughs of Operating 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 Operating 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.
- Provider/model namespace safety. API-profile ids and CLI model ids are different namespaces; a single validator (
swarm/core/model_namespace.py) ensures no seat or picker ever offers/applies a model its provider cannot run — e.g. an API slug is never passed toagy --model, and the opencode picker hides the app-onlyopencode/*tier. - Browser / computer control. Sandbox
sandbox_browser_*tools (navigate / click / type / snapshot / screenshot) run Playwright + Chromium inside the agent's sandbox over a persistent CDP port, with a live sandbox display (VM id/status/preview, credential env-var name) in the UI (#1200, #1201). - Client-side WebGPU provider (experimental, OFF by default). A flag-gated in-browser provider with a Web Worker generate protocol, resumable model download + integrity + cache management (#1288).
- Desktop systray.
os-marchy-systray— bots in the system tray, grouped by rig/team, local auto-detect or a remote OS instance (#1306). - Hack code font. Hack is self-hosted and is the default code-block font; also selectable in Settings → Aesthetics. Provider dropdowns use brand SVG icons (#1249).
- Rigs. Teams rebranded to Rigs with an OpenRig topology view;
role@rigqualified addresses (sections = dynamic rigs, teams = static rigs) (#1222, #1224). - Chat polish. Navbar Agent & Session pickers, agent-config sidepane, per-agent composer drafts (typed text survives agent switches), live WS rendering, bounded streaming with a configurable fallback base URL, configurable agent LLM timeout.
- Remote ask-user bridge. A remote agent can ask a question mid-turn and resume after your answer (TrueForge pauses resume via
user.tool_response) (#1307).
Letta's dedicated remote was removed (Letta migrates to a plain OpenAI-compatible API profile) (#1332).
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/operating-swarm.git
cd operating-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/os-api defaultPorts: On a standard
docker compose/os-apisetup, the Operating Swarm ASGI + WebUI listen on:8000. If an upstream LLM gateway or proxy already binds:8000, OS can be run on an alternate port (such as:8002). Ensure client API and session calls target the OS server port. For configuration details, see 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.
Without dist/, / falls back to Django templates. Rebuild after SPA pulls. Auth: docs/AUTH.md (websocket needs a session cookie; bearer does not auth WS).
- 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 PyPI0.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.
- 2026-09 (late) — Provider/model namespace safety, browser control + live sandbox display, experimental client-side WebGPU provider,
os-marchy-systray, Rigs +role@rig, Hack code font, per-agent composer drafts. See What's new above.
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, TrueForge (and nested Operating Swarm / OS instance). Variants are adapters, not extra kinds. Herdr is SSH-shaped, not another HTTP remote. (Letta's dedicated remote was removed — Letta is an OpenAI-compatible API profile now.) |
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): 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.
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.
Under the hood a team/workflow is a Python blueprint class (ADR-005). That is the power-user path.
Happy path: ask Support in natural language. Underspecified “create a team” is Socratic; “Create a BA → Engineer → Tester workflow” drafts immediately. You do not write Python. Add as agent or Save as blueprint persists the draft. Code stays hidden unless you choose View / edit code. The product bootstraps more of itself this way (REQ-158 / #567 / #440). Guided path + checklist (GitHub-only): docs/SUPPORT_NL_BLUEPRINTS.md.
Mermaid, kind bases, and the :8001 seed live on docs/DEVELOPER.md. Worked configs: docs/examples/openai-agents-handoff-graphs/ (REQ-156 / #564). Demo roster names (Mode A kind-clear vs Mode B personas): docs/SHOWOFF_DEMO_AGENTS.md (REQ-135 / #526). Kind-base ADR: ADR-005 (REQ-159 / #570).
| 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. In-tree stub at packaging/open-swarm-alias/ (#296) will be the next PyPI open-swarm (deprecation alias → os-core); that upload waits until os-core is on PyPI. |
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/operating-swarm.git
cd operating-swarm
uv sync --all-extraspip 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.
export OPENAI_API_KEY="sk-..."
# CLI kind — discover installed agentic CLIs
uv run os-cli cli-agents --init --write --check-auth
uv run os-cli launch cli_agent --message "What CLIs can you see?"
# Blueprint kind — same recipe as an OpenAI `model` id
uv run os-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 os-cli remotes
# uv run os-cli remotes place <id>
# OpenAI-compatible door (after the WebUI / compose steps above).
# Standard compose/os-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. Remotes: docs/REMOTE_HARNESSES.md. Herdr: docs/HERDR.md. CLI wrap / fusion (not the first team story): docs/CLI_FUSION.md. MoA consensus (not the first team story): docs/MOA.md.
Operating 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/operating-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/.
- docs/ANNOUNCE.md — launch spiel + hero GIF (REQ-136 / #529)
- docs/VISION.md — where we are going (kinds, WebUI, remotes)
- docs/GLOSSARY.md — kinds, Team vs Profiles vs roster
- USERGUIDE.md —
os-clitasks os-marchy-systray/— desktop tray client (bots grouped by rig/team; local or remote OS)- docs/REMOTE_HARNESSES.md · docs/HERDR.md
- docs/AUTH.md · CONFIGURATION.md (
swarm_config.example.json) - FEATURE_STATUS.md · ROADMAP.md
- docs/DEVELOPER.md — gateway,
/v1/responses, dated history, contribution pointers - docs/diagrams/ — visual docs: hero overview, system architecture & trust boundaries, deployment, request/auth/async sequence diagrams, data flow, integrations, security, operations, and the legacy abstraction maps (editable HTML/SVG sources + generated previews)
- CONTRIBUTING.md
Recipes and pattern diagrams stay in docs/EXAMPLES.md and docs/ORCHESTRATION_PATTERNS.md — they are not the front door.
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): FEATURE_STATUS.md.
Operating Swarm began as Open Swarm, an extension of OpenAI’s experimental Swarm, and migrated to the openai-agents SDK for agents, tools, and handoffs.
MIT — see LICENSE. Attribution and vendored-asset notices live in NOTICE.
Issues and PRs welcome. See CONTRIBUTING.md and docs/DEVELOPER.md.