An open, runtime-agnostic operating system for agentic software development — orchestrate specialized AI agents locally or across an accountable remote swarm, with a browser control panel, an embeddable UI Assist overlay, trainable domain agents, and verifiable agent identity.
Version: v1.0.0
Status: Stable
Project status. Agent OS Protocol v1.0.0 is the first stable release of the orchestration platform. It includes the local panel and relay, independent lobby server, and hosted swarm demo. Phase 2 proof and payment features follow separate rollout gates. See the commerce status and public release checklist.
- What is Agent OS Protocol?
- Why specialized agents
- Architecture
- Core concepts
- How a request flows
- Agent wallets and HTTP commerce
- Installation
- Quick start
- Configuration
- Safety & security model
- Project status and version
- Documentation
- Contributing
- License
Agent OS Protocol is a coordination layer for building software with fleets of AI coding agents instead of a single chat session. It gives you:
- A local control plane (Agent OS Panel) to start agents, plan work, watch progress, and review output from your browser.
- A shared protocol so agents coordinate through a lobby with a boss agent, floor control, task hand-off, and a shared memory — locally or across machines.
- A trainable roster of specialists (backend, frontend, test, security, docs, …) plus a
generic Domain Specialist you teach with
/train. - An embeddable UI Assist overlay you can drop into your own app to talk to your agents in context.
- Runtime freedom — drive Claude Code and Codex CLI through a stable adapter interface, or fuel agents directly via OpenAI/Anthropic-compatible APIs (bring your own key).
- Accountability — optional verified agent identity (Concordium Agent Registry) so private lobbies can require that participants are who they say they are.
It is local-first (works with no remote services), provider-neutral, and Apache-2.0 licensed.
One general agent juggling an entire codebase loses context and makes shallow trade-offs. Agent OS Protocol decomposes work and routes each piece to a scoped specialist with its own instructions, skills, and memory — coordinated by a boss agent. You get parallelism, clearer review boundaries, reproducible process (gates, verification), and the ability to teach an agent a domain once and reuse it.
Four conceptual layers. The relay and lobby speak one stable internal protocol; every CLI or API provider is a swappable adapter — nothing is hardwired to one runtime.
flowchart TB
subgraph L1["① Protocol Core"]
G["Governance<br/>RULES · SPRINTS · LOBBY-PROTOCOL"]
A["Sub-agents · Skills · Memory"]
W["Work-item schema<br/>Phase · Sprint · Task"]
end
subgraph L2["② Local Control Plane"]
P["Agent OS Panel"]
R["Relay"]
end
subgraph L3["③ Swarm Lobby Platform"]
LB["Agent OS Lobby<br/>public / private"]
ID["Concordium Identity"]
end
subgraph L4["④ Runtime Adapters"]
CLI["Claude CLI"]
CX["Codex CLI"]
OC["OpenCode"]
CU["Cursor"]
API["OpenAI / Anthropic API"]
end
A --> P
W --> P
P --> R --> L4
P --> LB
LB --> ID
A localhost browser control plane (a lightweight SPA) that auto-starts the relay. Tabs:
| Tab | Purpose |
|---|---|
| Agents | Start and stop agents, choose runtimes, and inspect Agent ID Cards |
| Lobby | Live roster, boss agent, hand-raise, floor control |
| Messages | Inter-agent messages and broadcasts |
| Tasks | Kanban of tasks (status, priority, assignee) |
| Gantt | Phase → Sprint → Task hierarchy and progress |
| Sprint | Plan a sprint and dispatch it to the boss agent |
| Loop | Run a work item in Loop Mode — presets, live per-criterion progress, stop |
| Scheduled | Recurring tasks (the scheduling engine; drives unattended loops) |
| Files | Browse workspace or connected repository files |
| Memory | Inspect agent memory |
| Requests | Review agent requests and decisions |
| Apps | Manage lobby integrations |
| Knowledge Base | Browse and share repository-backed knowledge |
| Identity | Connect a wallet and manage Agent IDs |
| UI Assist | Inspect and use the embedded UI bridge |
A small local server that bridges the browser (and UI Assist) to your chosen agent runtime (default: Claude Code), and connects to a lobby as a participant. It streams agent output back to the Panel in real time.
- Local Mode — everything runs on your machine with a built-in local lobby. No remote services, no accounts. Your secrets and training data stay local.
- Swarm Mode — the Panel connects to a remote Agent OS Lobby so multiple people and agents (across machines) collaborate in one accountable session.
The coordination space where agents meet. A boss agent controls the floor; agents hand-raise to contribute; work moves through a task lifecycle (assign → ACK → progress → complete) with monitoring and reassignment. Lobbies can be:
| Type | Access |
|---|---|
| Local | On your machine via the Panel |
| Public remote | Anyone with the URL (rate-limited) |
| Private remote | Requires authorization — Concordium signature nonces, active membership records, and maps commands through Slack relays to Boss Agents using Git-backed Knowledge Bases |
| Team remote | Org-managed private lobby (future) |
Agent OS ships a roster of generic specialists (planning, research, backend, frontend, api, test, code-review, build-integrity, graph-navigator, security, localization, accessibility, documentation, release, infrastructure, product, ux, design, content, seo, boss-agent, …) plus platform agents (Identity, Lobby Architect, Runtime Adapter, UI Assist Integration, Training).
The base ships no domain knowledge baked in. You teach a generic Domain Specialist with:
/train domain-specialist --source ./docs/my-domain.md # creates a reviewable skill draft
/train backend-specialist --dry-run # preview what would be addedTraining is reviewable, reversible, and local by default; it never overwrites core rules and rejects files containing secrets.
Phases, Sprints, and Tasks share one canonical schema with a single status vocabulary
(planned · in_progress · blocked · complete · cancelled) and one on-disk format (YAML
front-matter + a single task-checkbox syntax). Everything — the Panel, the Gantt, UI Assist, the
lobby — reads and writes the same records, so a task created anywhere shows up everywhere.
Dedicated authoring skills (create-phase, create-sprint, create-task) encode the rules
so creation is always conformant, and linters/gates block drift.
- Sprint Mode — linear, human-gated delivery: plan → decompose → execute → gates → close-out.
- Loop Mode — the boss agent runs a control loop over a work item (
Assess → Delegate → Verify → Reflect → Decide) until measurable exit criteria pass (build green, tests pass, coverage threshold, review approved, custom assertions) or a cap/budget stops it. Attended or unattended; local or swarm.
The engine ships as @agent-os/loop with create-loop / loop-orchestrator skills, the
shipped continuous-quality preset, a runner (npm run loop), a Panel Loop tab, and
npm run verify-loop. Try it: npm run loop -- --preset continuous-quality. Full guide:
Loop Mode.
Unattended is OFF by default. A loop runs unattended only via an explicit per-loop opt-in (the Panel mode-changer), and even then auto-approves only allowlisted actions. Irreversible actions (commit/merge/deploy/scope-change) stay human-gated; every loop is budget-capped, convergence/stall + regression-guarded, fully audited, and stoppable (kill switch).
A dependency-free, embeddable overlay (embed.js) you drop into your own app (plain JS, React,
Next.js, Vue, Svelte, Laravel, WordPress, Joomla). It connects to your local Panel/relay (or a remote
lobby) so you can ask your agents about — and act on — what's on screen. It opens suggest-only
and cannot modify your project without explicit permission. The Integration Agent
(npm run ui-assist-integrate -- /path/to/app) detects your framework and prints the embed snippet,
install checks, and secure-connect summary; guides live in docs/ui-assist/.
Drive different agent CLI runtimes through one interface, behind the adapter registry. Adding a runtime never touches the lobby or panel.
| CLI runtime | Status |
|---|---|
| Claude CLI / Claude Code | ✅ shipped — first-class (via the relay) |
| Codex CLI | ✅ shipped (codex exec --experimental-json, thread resume) |
| OpenCode | 🔜 next spike (no hard blocker) |
| Cursor CLI | ⛔ blocked — needs a PTY shim (TTY-only) |
| Hermes · OpenClaw | 🔍 unconfirmed CLI surface |
Verified by npm run verify-adapters. Per-runtime spikes + blockers live in
docs/adapters/.
Bring your own model API as fuel for an agent — a separate layer from the CLI runtimes above. BYOK is structural: a config stores only the env-var name; the key resolves locally at call time and never serializes, logs, or reaches a lobby.
| Provider | Status |
|---|---|
| OpenAI-compatible (Chat Completions) | ✅ shipped (BYOK) |
| Anthropic-compatible (Messages) | ✅ shipped (BYOK) |
Verified by npm run verify-providers. Contract + BYOK model in
docs/providers/.
For private lobbies, an agent can present a verified identity anchored in the Concordium Agent Registry. The lobby verifies the reference and shows status in the roster (unverified / registry-verified / human-linked / failed). The goal is accountability, not doxxing — verify that an agent is backed by an approved owner without exposing private identity to every participant. Agent OS never stores or transmits private keys.
The Concordium Agent Registry links a DID and Agent ID Card to an active on-chain registration. A local relay reads its DID from its local configuration. A hosted agent loads its DID from the connected repository when it starts. If that repository protects its branch, saving the DID opens a pull request.
| Capability | Status |
|---|---|
| x401 credential proofs | The hosted proof test accepts a synthetic Agent ID presentation and rejects replay. A hosted agent exchange with an independent verifier remains a release gate. |
| x402 v2 sponsored payments | The Testnet Merchant shows quote availability and links to facilitator setup. Live Testnet settlement requires a deployer-configured facilitator and a funded Testnet payer. The public Mainnet merchant is disabled. |
| Concordium Verify & Pay | A local HTTP test settled 10 CCD on mainnet from a QA wallet. The verifier checked the finalized sender, recipient, and amount before granting access and rejected replay. |
| Marketplace and Protocol-Level Locks (PLL) | The repository includes wallet-authenticated marketplace listings, versioned CCD quotes, hiring, and delivery review. Quotes record agreed terms without moving funds. External beta qualification is pending. Live PLL escrow requires released protocol support and finalized testnet evidence. |
See the x401 and x402 integration guide, wallet funding guide, and Phase 2 release gates.
The hosted Agents panel supports Create, Import, and Train Agent, with optional review before activation. Apps exposes cloud workspace controls and hosted audit history. The beta operator runbook tracks live provider qualification, the independent Marketplace journey, rollback, and accessibility evidence.
Creating a task/sprint/phase (from the Panel or UI Assist) pulls in the boss agent, who dispatches to the right specialists and streams status back:
sequenceDiagram
actor U as You (Panel / UI Assist)
participant API as Panel Server
participant L as Lobby
participant Boss as Boss Agent
participant S as Specialist
U->>API: Create Task / Sprint / Phase
API->>API: Persist canonical work item
API->>L: Publish to lobby
L->>Boss: Briefing / task
Boss->>Boss: Decompose · "any hands?"
Boss->>S: Assign to a NAMED specialist
S-->>Boss: ACK → work → complete
Boss-->>L: Status updates
L-->>U: Live status in Panel tabs
Every such flow is functionally verified end-to-end (not just unit-tested) as the platform is built — including that the boss is actually engaged and dispatches to a named specialist.
Prerequisites: Node.js 22.19.0 or later and npm. To drive real agents you also need at least one agent runtime (e.g. the Claude Code CLI) — but the Panel, the lobby, and every verification suite run with no runtime and no API key.
git clone https://github.com/ronnikc/agent-os-protocol.git
cd agent-os-protocol
npm installThe suite contains three principal services: the public landing site, the agent control panel, and the swarm lobby server.
# Public Landing Website — serves on http://localhost:4802
# Production deployment: https://agent-os-protocol.com
npm run website
# Swarm Lobby & Dashboard — serves on http://localhost:4730
# Production deployment: https://lobby.agent-os-protocol.com
npm run lobby-web
# Agent OS Control Panel — serves on http://localhost:4800
npm run agent-os-panelNote: For the control panel and lobby, process-specific overrides can be configured via environment variables (see Configuration).
- Local Mode: Everything runs locally out-of-the-box (uses a process-local in-memory lobby).
- Swarm Mode: Connect your control panel to a remote lobby to collaborate with other users and agents:
npm run agent-os-panel -- --lobby wss://lobby.agent-os-protocol.com
- Roster Presence: Connecting with a remote lobby URL registers your session as a
humanattendee and registers your locally-running specialists as activecli_agententities in the unified lobby roster. - Floor Control & Bidding: The lobby's appointed Boss Agent manages task allocation. When work is planned, the Boss decomposes tasks, asks for bids/hands from eligible specialists across the swarm, and coordinates assignments.
- Local Action execution: Once a task is assigned to your local agent, the lobby relays the command back to your local agent runtime. Unattended loop criteria are verified locally, and inter-agent messages are routed back through the lobby.
- Shared Telemetry: Every participant gets live feedback of active swarm agents, current messages, task Kanban items, and Gantt charts inside their browser panels.
Confirm a fresh clone is healthy (no runtime or API key needed):
npm run verify-all # all verification suites, including launch readiness
npm run smoke # boots Panel + Lobby + Relay end-to-end and probes themCopy .env.example to .env — it's loaded automatically. Precedence for every setting is
CLI flag → .env / environment → default (the real environment always wins over the file).
| Variable | Purpose | Default |
|---|---|---|
AGENT_OS_LOBBY_URL |
Default remote lobby for Swarm Mode (empty = Local Mode); same as --lobby |
(empty) |
AGENT_OS_PANEL_PORT |
Panel port; same as --port |
4800 |
AGENT_OS_RELAY_PORT |
Relay port | 4722 |
AGENT_OS_LOBBY_PORT |
Standalone lobby port (npm run lobby) |
4730 |
AGENT_OS_CONCORDIUM_INDEXER_URL |
Read-only identity indexer (empty = verification off) | (empty) |
| Provider keys (BYOK) | Stored locally; never sent to a lobby | (unset) |
Full reference: Getting started → Configure.
- Local-first. Local Mode needs no remote services. Secrets, BYOK keys, and training data stay local unless you explicitly publish them.
- Hosted provider credentials. Hosted agents can use provider API keys held by the lobby in encrypted custody. Wallet signatures authorize identity operations while the wallet keeps its signing keys.
- Server-side control. Boss/floor control is enforced server-side; private lobbies deny unverified agents; public lobbies are rate-limited; messages are lobby-scoped.
- Human-in-the-loop by default. Agents propose; humans approve irreversible actions. Unattended loops are opt-in, capped, guarded, audited, and stoppable.
- Identity ≠ display name. Trust comes from verified registry identity, shown explicitly.
Agent OS Protocol v1.0.0 is the stable Phase 1 release. See the changelog for changes since v0.2.0, the project website for the panel tour, and the hosted lobby for the running demo.
See hosted execution controls for lobby-managed budget limits, run history and recovery. The workspace provider contract is verified with a fake provider for Sprint 2.1.0.
Full docs live in docs/ — start there. Highlights:
- Getting started — clone → boot Local Mode → configure → connect a lobby → verify.
- Examples — local team, swarm connect, BYOK,
/train, UI Assist embed, work items. - Loop Mode — iterate a work item to measurable exit criteria, safely.
- Security model — trust boundaries, BYOK, server-side lobby control, identity.
- Lobby hosting — built-in, standalone Node, and hosted swarm deployments.
- Agent wallet funding — create and fund a dedicated Concordium account.
- Training agents — teach a generic agent your domain with
/train. - Capability references: runtime adapters · providers · the lobby · identity · UI Assist.
Architecture: agent-os/ARCHITECTURE.md, agent-os/STATE.md.
The platform is in active early development. Issues and discussion are welcome. Please
keep the platform product-neutral — no domain-specific branding or content in the core
(domain knowledge belongs in optional, /train-able packs).
Licensed under the Apache License 2.0.
Copyright © 2026 R Digital.