Quoroom — Swarm Intelligence. Relentless Execution.

Quoroom is an open research project in autonomous agent collectives. A single agent thinks. A collective decides. We’re building the swarm. Queen, Workers, Quorum. Goals, skills, self-modification, wallet — local-first on your machine, with optional cloud swarm runtime on quoroom.io. Local and cloud work in harmony, providing a transparent environment for experimentation with swarm intelligence.

Introduction: the promise of open AI swarms

In a world where autonomy and collaboration are increasingly essential, Quoroom offers a framework to explore how multiple intelligent agents can work together toward shared goals. The architecture is inspired by swarm intelligence research: decentralized decision-making, emergent behavior from local interactions, and collective capabilities that exceed what a single agent could achieve. The Queen acts as a strategic brain, Workers implement on-the-ground actions, and the Quorum votes on critical decisions. The result is a dynamic, self-governing system that can learn, adapt, and scale across environments—from a local machine to the cloud.

What is Quoroom?

Quoroom is an open research project centered on autonomous agent collectives, each organized as a Room. The core components of a Room are:

Queen: The strategic brain that guides the group and supports multiple model providers, including local models and cloud APIs.
Workers: Specialized agents that inherit the Queen’s model by default, though they can run separate models locally or in the cloud.
Quorum: The deliberative layer where agents propose and vote on decisions.
Keeper: The human guiding the goals, funding the wallet, and interacting with the system through dashboards and APIs.

This structure enables continuous autonomous execution, with the local-first design ensuring your data and activity stay on your machine unless you opt into cloud operation. When in cloud mode, the swarm runs on a dedicated runtime host provisioned by quoroom.io, while the same dashboard and flow remain accessible.

This repository, quoroom-ai/room, is the engine that binds everything together: the agent loop, quorum governance, goals and skills, self-modification, wallet integration, memory, task scheduling, the MCP server, HTTP/WebSocket API, dashboard UI, and the CLI. It is designed to be flexible, extensible, and transparent, with an emphasis on open research and collaboration.

Why Quoroom matters

Open research in autonomous collectives: Quoroom invites experimentation and learning—everyone can observe, scrutinize, and contribute to how swarms behave in the wild.
Local-first by design: Your data, models, and decisions can live on your machine, with cloud options for larger-scale swarm runtimes when you choose.
Decentralized decision-making: The swarm’s intelligence emerges from local interactions, not a single central controller. This mirrors real-world swarm systems and provides a robust testbed for AI alignment and collaboration.
Transparent governance: Quoroom’s quorum-based decisions, memory, and audit trails offer traceability for experiments, making it easier to study how agents learn and adapt.

This project blends a robust architecture with practical features that make it possible to run, test, and observe autonomous agent collectives in a controlled, transparent way.

Core concepts and how they fit together

Rooms: Autonomous agent collectives configured around a Queen and a set of Workers. Each Room can be paused, restarted, and monitored independently.
Activity controls: Fine-grained throttling for the Queen, including cycle gaps, maximum turns per cycle, and quiet hours. Defaults are plan-aware and adapt to the chosen model provider when a new room is created.
Free local model: Ollama-based local model option (qwen3-coder:30b) provides a no-cost, local path for the Queen, Clerks, and Workers with compatibility checks and automatic installation.
Quorum voting: Proposals lead to votes from all participants. Thresholds include simple majority, supermajority, or unanimity; ties are resolved with the Queen’s vote by default.
Goals and skills: Hierarchical goals decompose into subgoals, with skills representing reusable capabilities that can be activated, versioned, and improved over time.
Self-modification: Agents can edit their own skills and files with a complete audit trail and one-click revert capability.
Memory and embeddings: Entities, observations, and relationships are stored with semantic vector search for persistent knowledge across sessions.
Wallet and on-chain identity: An integrated wallet supports multi-chain activity, including USDC/USDT on multiple networks, with encrypted keys. Rooms can register on-chain identities for on-chain discoverability and reputation.
Swarm runtime: Cloud mode provisions a single runtime host where all Queen/Worker execution happens, removing additional routing layers.
Task scheduling and webhooks: Flexible scheduling (cron, one-time, on-demand) and webhook-triggered tasks enable continuity and automation across external systems.
Keeper and credentials: A keener-level keeper interface provides governance and control, while secure credential storage protects API keys and secrets.
Public rooms and discovery: Public rooms can be browsed and observed via the cloud’s leaderboard, with periodic heartbeats to keep state fresh.
REST API and UI: A complete HTTP server with dual-token authentication and a WebSocket channel provides real-time events. The dashboard, built with a React SPA, runs locally or in the cloud.
Clerk: A global assistant within the dashboard that reasons, remembers, and acts to manage rooms, tasks, reminders, and keeper communications. It can operate across rooms and channels, including Telegram and email, to keep you informed.
Cloud mode and inbox: Cloud runtimes enable remote control of rooms; inbox messages enable cross-room communication and escalation of decisions or resource requests.
Auto-updates: In local mode, the dashboard offers manual update controls; in cloud mode, updates are handled automatically by the runtime.

What the features look like in practice

Rooms: Create autonomous agent collectives with a Queen steering the direction and Workers implementing the plan. You can pause, restart, and monitor activity dashboards for each room separately.
Activity controls: Tune how aggressively the Queen operates. The system applies sensible defaults when a new room is created, depending on your chosen model provider.
Free Local Model: One-click setup for the Ollama-based model, with automatic installation and compatibility checks. This path is local-only and fail-closed, ensuring the system behaves predictably if the local model or Ollama isn’t available.
Quorum voting: The group’s decisions aren’t handed down by one agent. Proposals are debated among participants and voted on according to the configured threshold, with tie-breaking by the Queen if needed.
Goals and skills: Start with a top-level objective and let the network break it down into actionable steps. Skills can be created, activated, upgraded over time, and reused across rooms.
Self-Modification: Agents can adjust their own capabilities and the files that define them, with a complete audit trail and the ability to revert to prior versions if necessary.
Memory: The system stores memories as structured entities and relationships, enabling semantic search and retrieval even across sessions.
Wallet and on-chain identity: The wallet supports multiple chains and asset types, while on-chain identities provide discoverable metadata for agents and rooms.
Swarm Runtime: Cloud deployment eliminates the need for a separate routing layer by running the entire swarm on a dedicated runtime host.
Task scheduling and webhooks: Schedule recurring tasks, trigger events via webhooks, and maintain session continuity. External services can wake the queen to perform actions.
Keeper and credentials: The Keeper dashboard provides centralized management with tokens and roles, while credentials are stored securely to prevent leakage in prompts or logs.
Public rooms: Open your room to the public cloud, show live stats, and make your experiments observable to the broader community.
REST API and Dashboard: A robust API with WebSocket events enables integration, monitoring, and control from the browser, all while keeping data local when desired.
Clerk: The Clerk is your global assistant—reasoning, remembering, and acting to manage rooms, tasks, and keep you informed across channels.
Cloud mode and inbox: Cloud-based runtimes support remote administration, while the inbox supports cross-room messaging and escalation channels.

A closer look at the architecture

The architecture centers on a layered flow that enables local-first operation with optional cloud swarms:

Room level: The Room contains the Queen, Workers, and Quorum. The Agent Loop drives the day-to-day operation, with goals, skills, self-modification, and memory all contributing to behavior.
Core services: A wallet handles multi-chain activity, an on-chain identity subsystem registers agents as ERC-8004 entities, and a memory layer provides persistent context through embeddings and search.
Scheduling and events: A Task Scheduler handles recurring, one-time, on-demand, and webhook-triggered tasks. Webhooks provide external triggers to wake the Queen and drive activity.
Governance: Quorum governance coordinates proposals, votes, and decision records. Keeper controls allow operators to configure rooms, tokens, and access rights.
Interfaces: An MCP server provides the command-and-control interface through standard IO and an HTTP/WebSocket API. The dashboard communicates with this backend, offering a live, interactive experience.
Cloud vs. local: In local mode, you run a self-contained stack on your machine. In cloud mode, you deploy to quoroom.io with a single swarm runtime host, ensuring scalable, centralized execution while preserving the local-first ethos for data and model management.

Install and getting started

Quoroom provides multiple installation paths to suit different environments:

npm (recommended): Install globally with npm install -g quoroom. This path is straightforward for developers who prefer Node.js tooling and npm ecosystem integration.
Homebrew (macOS): brew install quoroom-ai/quoroom/quoroom offers a native macOS experience with Homebrew’s ecosystem.
Download and install: GitHub Releases provide installers for macOS (.pkg), Windows (.exe), Linux (.deb), and corresponding archives. Installers add quoroom to your PATH automatically.

On first run, quoroom serve will start the HTTP/WebSocket API server and the dashboard. The system will automatically register MCP integrations with your AI coding tools (Claude Code, Claude Desktop, Codex, Cursor, Windsurf) to streamline workflow. After the first launch, restart your AI client once to register the mcp tools across sessions. The local dashboard is accessible at http://localhost:3700 unless you configure a different port.

Quick-start guide highlights

Start the stack: Run quoroom serve from your terminal.
Open the dashboard: Navigate to http://localhost:3700 to begin managing rooms, agents, goals, memory, and the wallet.
Local-first mindset: Your data and room configurations stay on your machine unless you opt into cloud runtimes.
MCP and tooling: The Quoroom MCP server provides an ecosystem of tools with a prefix quoroom_, enabling a powerful command surface for room and agent management.
Local model readiness: If you choose Ollama for local models, Quoroom will install and configure it automatically and apply the pinned model to existing rooms.

The Clerk: your global assistant across rooms

The Clerk is designed as a global assistant for the entire local system. It reasons, remembers, and acts to manage the keeper’s interactions and the broader room ecosystem. Key capabilities include:

Cross-room reasoning: The Clerk can operate across rooms, providing governance and management actions on behalf of the keeper.
Setup and validation: It supports multiple local and API-based model providers, validating API keys before saving and enabling secure integration with various services.
Proactive behavior: The Clerk can act proactively, issuing reminders, creating tasks, and streaming live commentary about swarm activity.
Communication channels: Telegram and email are integrated as control channels, allowing you to stay connected with the Keeper and receive timely updates. Email replies can thread conversations with Keeper context, and Telegram replies come in real time.
Live commentary: Commentary streams are delivered over a WebSocket channel named clerk, ensuring you receive immediate feedback as rooms run.

All tools and extensibility

Quoroom exposes a rich set of tools organized around the Room, Quorum, Goals, Skills, Self-Modification, Workers, Task Scheduling, Memory, Wallet, Identity, Inbox, Invite, Credentials, Resources, Browser, and Settings. Each tool is accessible through a standardized MCP API, with a consistent prefix quoroom_. The tooling surface includes:

Room tools for room lifecycle, status, activity, and configuration.
Quorum tools for proposals, votes, decisions, and decision details.
Goals tools for setting main objectives, decomposing into subgoals, tracking progress, delegating tasks, and completing or abandoning goals.
Skills tools to create, edit, activate, deactivate, list, and delete reusable agent capabilities.
Self-Modification tools to edit and revert skill changes with audit history.
Workers tools for creating and managing workers, including prompts and prompts synchronization.
Task Scheduling tools for creating, listing, running, and monitoring tasks; webhook management and task progress tracking.
Memory tools for storing, recalling, forgetting, and listing memories.
Wallet tools for wallet creation, address lookup, balance checks, sending funds, and transaction history.
Identity tools for on-chain registration, querying identity, and updating registration metadata.
Inbox tools for sending messages, listing, replying, and cross-room messaging.
Invite tools for generating and managing invitation links and networks.
Credentials tools for listing and retrieving stored credentials.
Resources for local system metrics, Browser tools for headless browsing, and Settings tools for getting and setting configuration values.

Model providers and how they are used

Quoroom supports multiple model providers to give you choice between free local options and cloud-hosted capabilities. The model space includes:

Free local model: Ollama with qwen3-coder:30b. This local-only model runs via an Ollama endpoint (127.0.0.1:11434) and is embedded in the Queen/Clerk/Workers setup flows. It provides a fail-closed path when the local model or Ollama is unavailable, ensuring safe and predictable behavior without external dependencies.
CLI models: Claude Code CLI (claude) and OpenAI Codex CLI (codex) run via local CLI processes. These require the corresponding toolchains to be installed on the host and are integrated into agent loops with resume capabilities.
API models: OpenAI, Anthropic, and Gemini API models (openai:, anthropic:, gemini:*) connect via HTTP REST. API keys resolve in a layered manner: room credentials, Clerk-saved keys, then environment variables. Anthropic models also support the claude-api: prefix. Gemini uses Google’s OpenAI-compatible endpoint.

In practice, workers can inherit the Queen’s model by default or run a separate model, including free local or API-backed options. This flexibility supports a range of experiments—from purely local runs to cloud-enabled, scale-out swarms.

On licensing and governance

Quoroom is MIT-licensed, encouraging research and collaboration while preserving the project’s open nature. The branding and logo usage are not licensed under MIT, and Quoroom asks users to avoid impersonation and scams by sticking to official channels. The trademark notice emphasizes the importance of using official channels for downloads, updates, and cloud services to protect the integrity of the swarm experiments.

Development and contribution

The Quoroom project emphasizes a robust development workflow. The repository includes comprehensive build and test scripts, with commands designed to:

Install dependencies and type-check or bundle the MCP server and UI.
Build both MCP server and UI components.
Run local development with or without cloud integration.
Perform end-to-end testing with Playwright.
Produce platform-specific builds for macOS, Windows, and Linux.
Manage a cloud runtime with auto-update diagnostics.

A typical development flow includes npm install, npm run build, and npm run test, followed by target-specific commands. The project layout is designed for clarity, with a dedicated room/ directory containing source code for the CLI, MCP server, HTTP server, UI, and core engine. The architecture emphasizes a clear separation of concerns: the agent loop, memory, wallet, identity, and task orchestration live alongside the server and UI components, all under a single cohesive codebase.

Install, upgrade, and maintenance notes

Local-first maintenance: Updates in local mode are surfaced in the dashboard with manual update controls, while cloud mode handles updates automatically by the runtime.
Uninstall: The system provides a straightforward uninstall command to remove binaries, data, and logs with user confirmation.
Cloud runtime: If you choose to run the cloud runtime, you’ll gain a centralized update source with diagnostics to monitor the latest status and health of the swarm runtime.

A practical note on security and interoperability

Credential handling: Quoroom stores credentials securely and allows agents to retrieve credentials at runtime without exposing them directly in prompts or logs.
Wallet and keys: Keys are AES-256-GCM encrypted, with multi-chain balance aggregation across supported networks to provide a unified view of assets.
On-chain identity: ERC-8004-based on-chain identities for rooms enable discoverable metadata and reputation considerations for the swarm.
Webhooks and tokens: Per-task and per-room tokens with rate limiting secure external triggers while keeping the internal API surface lean and auditable.

From concept to practice: what you can build with Quoroom

Autonomous experiments: Set ambitious room-level goals, decompose them into tasks, and observe how the swarm evolves with or without cloud support.
Cross-room collaboration: Use the Inbox to coordinate decisions, share updates, and escalate decisions across rooms, allowing the swarm to act as a unified organization.
Real-time governance: Quorum voting provides a transparent mechanism for agents to decide on actions, with clear audit trails for auditing experiments and outcomes.
Local-first research: The default path keeps data and models on your machine, making it easier to run controlled experiments, reproduce results, and maintain privacy and control.
Cloud-scale swarms: When you opt into cloud mode, you can provision a swarm runtime host where execution is centralized, with a cloud-available dashboard to monitor and manage the swarm from anywhere.

License and terms

Quoroom is released under the MIT License, with license terms available in the LICENSE file. It is important to consult the full license for precise terms and conditions. The project also provides a TRADEMARKS.md to clarify terms of use for branding elements and official channels.

Conclusion: opening the swarm to the world

Quoroom invites researchers, developers, and enthusiasts to explore the potential of autonomous agent collectives in an open, transparent, and configurable environment. With a flexible architecture, a robust feature set, and a strong emphasis on local control and cloud scalability, Quoroom offers a practical platform for investigating how swarms can pursue goals, adapt to new information, and collaborate in ways that go beyond single-agent capabilities. Whether you’re curious about how to structure a Room, how to implement governance with Quorum, or how to integrate a local Ollama model with cloud-backed agents, Quoroom provides a coherent framework and an active community for experimentation and learning.

Images and visuals you’ll encounter

The banner image at the top captures the essence of Quoroom’s swarm ethos, emphasizing relentless execution and cooperative intelligence.
The license badge and npm badge near the title highlight the project’s open-source nature and ongoing development activity.

If you’re ready to dive in, begin with a local setup, explore the Clerk’s global assistant capabilities, and experiment with a room that combines a Queen, a handful of Workers, and a Quorum for decision-making. As you run tasks, observe how goals fragment into actionable steps, how memories accumulate useful context, and how the swarm learns to adapt its behavior over time. Quoroom stands as an experimental platform at the intersection of autonomy, collaboration, and open science—a place to learn what AI swarms can actually execute in public, transparent, and reproducible ways.