Operating Swarm (OS)

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). 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.

Demos

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.

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/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 default

Ports: On a standard docker compose / os-api setup, 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).

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.

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.

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). 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).

Install (version honesty)

# What main actually runs
git clone https://github.com/matthewhand/operating-swarm.git
cd operating-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 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.

Pinokio (local sideload)

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/.

Links

• 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-cli tasks
• 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 architecture stack, taxonomy tree, lifecycle state machine, and delegation sequence diagrams
• CONTRIBUTING.md

Recipes and pattern diagrams stay in docs/EXAMPLES.md and docs/ORCHESTRATION_PATTERNS.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): FEATURE_STATUS.md.

Acknowledgements

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.

License

MIT — see LICENSE. Attribution and vendored-asset notices live in NOTICE.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md and docs/DEVELOPER.md.