Quoroom: a self-governing AI agent swarm you run locally over MCP

What Quoroom actually solves, and for whom

Most agent frameworks give you one loop and one model. Quoroom's premise is that a single agent thinks, while a collective decides. The unit of work is a Room: a self-governing swarm containing a Queen that strategizes, Workers that execute, and a Quorum that votes. The README describes the target audience indirectly, as an open research project in autonomous agent collectives, and the package.json description is blunter: "Open-source local AI agent framework, Queen, Workers, Quorum. Experimental research tool." That word experimental is doing real work.

This is for someone who wants to run a persistent, goal-driven collective on their own hardware and inspect what it does. The README frames the motivation as transparency: continuous autonomous execution is already happening behind closed doors, and the project wants it to happen in the open. The human role has a name too. The Keeper sets goals and funds the wallet. If you are looking for a drop-in task runner with a stable API contract, the framing here should give you pause rather than reassurance.

Queen, Workers, Quorum: how the engine is wired

The repository layout confirms the shape of the system: src/ holds the engine, with an MCP server, an HTTP and WebSocket API, a React dashboard, and a CLI. The package.json entry points are telling. main is ./out/mcp/server.js and the bin entry quoroom is ./out/mcp/cli.js, so the MCP server is the primary artifact, not an add-on. The published files list only three outputs: cli.js, server.js and api-server.js.

Model routing is per role. The Queen supports a free local Ollama model, the Claude Code CLI, the Codex CLI, or OpenAI, Claude and Gemini APIs. Workers inherit the queen model by default and can be pointed at a separate model, including the local one. Governance is explicit: agents propose and vote, thresholds are majority, supermajority or unanimous, all voters including the keeper and workers carry equal weight, and ties fall to the queen's vote by default. State persists through a memory layer described as entities, observations and relations with 384-dimension vector search, and through a wallet holding an EVM address with encrypted keys.

The cloud split matters for anyone evaluating the architecture. The README states that cloud rooms provision a single swarm runtime host and that all queen and worker execution runs there, with no additional execution routing layer. So local and cloud are not two schedulers over one worker pool. They are two places the same engine runs.

Installing Quoroom and running a first room

The README points to quoroom.ai as the local app and install surface, and the badge row lists platform installers: a .pkg for macOS, an .exe for Windows and a .deb for Linux, all linked from the latest release. The package is also on npm under the name quoroom, so a global install is available.

Start by installing the CLI globally.

npm install -g quoroom

The package exposes a single binary, quoroom, which maps to the compiled CLI. To bring up the HTTP server and dashboard, run the serve subcommand that the README names.

quoroom serve

The Dockerfile in the repository exposes port 3700 and its final command is node out/mcp/cli.js serve, so 3700 is the port to expect for the server. If you prefer containers, the image installs the Codex and Claude Code CLIs globally inside the container and copies the built engine and UI from a Node 20 build stage.

For a free local model, the README describes a one-click Ollama setup in the Queen, Clerk and Workers setup flows. According to the README, Quoroom runs compatibility checks, installs Ollama, pulls the pinned model ollama:qwen3-coder:30b, streams progress, and applies it across active rooms. It also states this path is local-only and fail-closed, meaning there is no paid fallback if the local model cannot run. Before you rely on it, confirm the model fits your machine; the README does not list hardware requirements.

Where Quoroom is the wrong tool

Self-modification is the feature most likely to bite. The README says agents edit their own skills and files with a full audit trail and one-click revert. That covers skills and files. It does not describe rollback for the wallet, for memory, or for the task schedule, and the README does not document rollback for those surfaces. If your workflow requires a guaranteed return to a prior state, the documented revert scope is narrower than the phrase self-modification suggests.

Activity controls are the second constraint. The README lists a configurable cycle gap, a max turns per cycle, and quiet hours, with plan-aware defaults applied when a room is created based on the model provider. Those are throttles, not budgets. Nothing in the README describes a hard spend ceiling on API-backed providers, which matters because the same document says the free local path is fail-closed while the paid paths are not described as capped.

The cloud story is also not this repository. The README's own table splits room (engine, HTTP server, UI) from a separate cloud repository holding the landing page, public rooms, PostgreSQL and swarm instance infrastructure. If you need the hosted runtime, you are depending on a service, not on the MIT-licensed code you just cloned. And the wallet is real money: USDC and USDT across Base, Ethereum, Arbitrum, Optimism and Polygon, with keys encrypted using AES-256-GCM. The README states plainly that Quoroom will never ask for wallet seed phrases or private keys. Treat any request for them as impersonation.

How Quoroom differs from a single-loop agent runner

The obvious comparison is a direct agent runner such as the Claude Code CLI, which the Dockerfile installs alongside Codex. Those tools give one model one conversation. Quoroom wraps them as a provider option for the Queen and adds a governance layer on top: proposals, configurable vote thresholds, equal voter weight, and a tie-break rule. The difference is not the model call. It is that a decision has to pass a vote before it becomes action, and that the vote is recorded against a room rather than a session.

A second comparison is worth making because the README makes it for you: local versus cloud. Local means the engine runs on your machine with your data directory, and the dev scripts show an isolated data directory pattern using QUOROOM_DATA_DIR. Cloud means a provisioned swarm runtime host on quoroom.io, public rooms, and a leaderboard where rooms register and send heartbeats every five minutes. The cloud member role is narrower by design: the README describes cloud member tokens as read-only plus limited collaboration endpoints for voting, resolving or replying, and marking read. Agent and user tokens get full dashboard and API control. That asymmetry is a deliberate trust boundary, and it is the clearest signal that the cloud product and the local engine are governed differently.

Maintenance, licence and what an upgrade costs

The last push to the default branch was on 2026-04-12. The most recent release in the list is v0.1.42 from 2026-03-02, while package.json declares version 0.1.43, so the manifest is ahead of the newest tagged release. The repository is not archived, but a five-month gap between the last push and today means the project is not being actively developed right now, whatever the release cadence looked like in early March. Plan for a quiet upstream.

The version number itself is the upgrade story. Everything is 0.1.x, which the README's own framing supports: this is an experimental research tool. There is no documented migration guide, no deprecation policy and no stated compatibility promise for the HTTP and WebSocket API. If you build against the REST API, pin the version you install and read the release notes before moving.

Licensing is MIT, and the LICENSE file is present at the repository root. One carve-out deserves attention before you redistribute anything: the README states that the code is MIT-licensed but the Quoroom name, logo and branding are not licensed under MIT, and it points to TRADEMARKS.md for the full terms. A fork that keeps the branding is a different risk than a fork that strips it. That is a factual boundary, not legal advice; read TRADEMARKS.md yourself.

Editorial conclusion

Adopt Quoroom if you want to watch a multi-agent collective make decisions on your own machine and you are comfortable with an experimental research project that has not been pushed since 2026-04-12. Do not adopt it if you need a stable orchestration layer with a documented rollback path for self-modification, or if you expect the cloud runtime to be open source: the README says the cloud repository is a separate landing page and PostgreSQL stack. Before committing, verify that the pinned Ollama model pulls on your hardware, that your chosen provider CLI is installed, and that the MIT grant actually covers what you plan to redistribute, because the repository states the name and logo are excluded.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. quoroom-ai/room on GitHub
4. README
5. Releases