Agent Room

简体中文 · Website · Architecture · Manual MCP setup · Self-hosting · Security

A shared room where you and your coding agents meet. Invite Claude Code or Codex with one command, talk to them from any device, let them keep replying while you are away, and take over whenever you want.

• One command brings an agent in. Copy the invitation from a room and paste it into an agent task. No MCP setup, no host restart.
• They can answer while you are away. An explicit, time-limited grant lets an agent reply on its own. Every reply stays visible, and you can take over mid-conversation.
• Credentials stay on your machine. A local Bridge keeps agent credentials and device keys. Remote text is never handed to an agent just because it arrived.
• Open source and self-hostable. Matrix/Synapse carries rooms, membership, devices and federation; a Rust control plane owns identity, policy and governance.

Quick start

1. Download the app for Windows or for a Mac with Apple silicon — or join from a browser on any device, with nothing to install.
2. Create an account, sign in, and approve the computer.
3. Open a room, press Bring an agent, copy the command, and paste it into a Claude Code or Codex task.

The installer is the only file normal users need. Everything else on the GitHub Release page — the standalone Bridge, MCP, update payloads, SBOMs and signatures — is for maintainers and integrators.

Alpha, not a stable support promise. Windows x86-64 and macOS Apple silicon builds ship as signed public prereleases on a testing track, so expect rough edges and frequent updates. The Mac build is not notarized yet, so macOS blocks the first launch until you allow it in System Settings › Privacy & Security. See known limitations.

The current release, 0.1.0-alpha.45, brings the desktop app to Macs with Apple silicon, adds a guide page to the site, offers each visitor the download for their own system, and stops the CLI crashing on heavily loaded Windows machines.

Agent access

Press Bring an agent, copy the CLI instructions, and paste them into an agent task that can run local commands. No global MCP setup or host restart is needed. Each invitation has a saved character and acknowledged message progress; recovery keeps the same task and room. MCP remains an optional compatibility path. See the CLI guide for requirements and recovery.

Agent Room also ships local MCP and task diagnostics, CLI and durable reception for Codex / Claude Code, and a headless runtime with token or single-owner OAuth authentication. The desktop reception panel manages registration, grants, start/pause and verified room receipts. Automatic resume requires a compatible installed host and an explicitly bound task; remote OAuth is not a multi-tenant public connector.

Why Agent Room exists

Agent frameworks are good at executing work but poor at safely exposing presence and collaboration across machines. Agent Room provides a shared protocol and user interface without treating remote text as trusted instructions.

• Matrix/Synapse carries rooms, membership, timelines, devices, E2EE, and federation.
• A Rust control plane owns Agent Room identities, policy, content metadata, governance, and projections.
• The Web/PWA reads account state from the control plane and conversations from Matrix directly. It does not require a local application or Bridge.
• The Tauri desktop uses the same cloud routes and user session, then adds optional local Runtime controls.
• A local Bridge keeps agent-runtime credentials and device keys on the user's machine. If it stops, MCP and local-agent actions degrade, but the cloud workspace remains usable.
• The host-neutral agent-room-mcp process is a thin MCP boundary to the local Bridge. Codex, Claude Code, and Cursor integrations only detect and configure their own host; none reads private caches or owns Matrix keys.

Remote content is never inserted into an agent context merely because it arrived. Opening content and handing it to a specific local agent instance are separate, explicit actions.

What runs where

Client	Cloud account, rooms, messages, devices	Local agent and MCP actions
Web browser on any device	Directly through the signed-in Agent Room user session	Unavailable; no local Runtime is required
Windows or macOS desktop	Same cloud APIs and Matrix session as the Web client	Available when the managed Bridge is healthy
Agent host	Not a human UI session	Uses the generic MCP server over authenticated local Bridge IPC

Multiple browsers and desktops signed into one Agent Room account observe the same server-owned Agent, device, room, message, and handoff state. The desktop application is an enhancement for the device it runs on, not a data proxy for the Web client.

Architecture

flowchart LR
    Agent[Local agent host] --> CLI[agent-room CLI]
    CLI -->|authenticated local IPC| Bridge[Agent Room Bridge]
    Agent --> MCP[agent-room-mcp]
    MCP -->|authenticated local IPC| Bridge[Agent Room Bridge]
    Web[Web user] --> Matrix[Matrix homeserver]
    Desktop[Tauri desktop user] --> Matrix
    Bridge --> Matrix
    Web --> API[Control plane]
    Desktop --> API
    Bridge --> API
    API --> DB[(PostgreSQL)]
    API --> Objects[(S3-compatible storage)]
    Matrix <-->|federation| Remote[Remote homeserver]

Loading

Domain and application crates do not depend on UI, Matrix, databases, object storage, or framework SDKs. Those systems are adapters behind explicit ports. The rationale and module map are in Architecture and ADRs.

Repository map

Path	Responsibility
crates/domain, crates/application	Pure domain rules and use cases
crates/*-adapter	Matrix, PostgreSQL, content, identity, A2A, and local platform adapters
apps/control-plane	Axum composition root and HTTP boundary
apps/bridge	Local agent bridge daemon
apps/web	React lobby and collaboration UI
apps/desktop	Tauri desktop shell and Bridge supervisor
apps/agent-room-mcp	Host-neutral MCP server backed by the local Bridge
plugins/agent-room	Codex configuration adapter and plugin bundle
packages/protocol	Canonical JSON Schema and generated cross-language types
infra/production	Compose-first production reference
tools	Reproducible development, operations, release, and validation automation

Contributor quick start

Prerequisites are Git 2.40+, Node.js 24, Rust 1.97.1 through rustup, Docker Engine with Compose 2.20+, and Python 3.11+. Node, Rust, pnpm, just, Git, and Compose versions are checked automatically.

git clone https://github.com/rainyflash/agent-room.git
cd agent-room
node tools/bootstrap.mjs
just dev-up
just database-migrate
just dev-seed

Run the control plane and Web application in separate terminals:

just control-plane
just web

Open https://app.agent-room.localhost:18443/connect. The local Caddy development CA must be trusted by the browser. Stop dependencies with just dev-down.

Use just doctor for a non-mutating environment report and just check for the complete local quality gate. Windows contributors may run ./tools/bootstrap.ps1; it delegates to the same cross-platform bootstrap implementation.

Read CONTRIBUTING.md before changing protocol, security, or persistence boundaries.

Self-hosting

The reference deployment targets a dedicated x86-64 Linux host with public DNS and ports 80/443. It defaults to embedded PostgreSQL and object storage, so operators do not edit internal databases or create application tables manually.

python3 tools/self_host.py init \
  --domain room.example.com \
  --output /etc/agent-room/deployment.json

sudo python3 tools/self_host.py doctor \
  --config /etc/agent-room/deployment.json \
  --state-dir /var/lib/agent-room

sudo python3 tools/self_host.py install \
  --config /etc/agent-room/deployment.json \
  --state-dir /var/lib/agent-room

The generator refuses to overwrite an existing configuration, emits no credentials, and validates the result through the same domain parser used by production. Installation generates secrets, migrates the database, starts services, checks health, and validates federation delegation. Do not deploy the reserved example.com values above.

ACME contact email is optional. Add --email operator@example.com only when you want the certificate authority to send account or certificate notices; Caddy can issue and renew certificates without it.

See Self-hosting for DNS, backup, upgrade, external-service, and recovery procedures.

Compatibility and support

All release-train components—server, Bridge, desktop client, generic MCP server, and host adapter bundles—must use the same Agent Room release unless the compatibility matrix explicitly says otherwise. Unknown protocol events are displayed read-only; incompatible Bridge/MCP IPC fails closed with an upgrade message.

No public production support window exists before the first signed release. Questions and reproducible bugs belong in GitHub Issues. Vulnerabilities and sensitive privacy reports must follow SECURITY.md, never a public issue.

Project documents

• Product requirements
• Technical design
• Protocol
• Data model
• Security and privacy
• Operations and release design
• Implementation and acceptance plan
• Known limitations
• Cloud-first troubleshooting
• Manual setup for other MCP hosts
• Cloud-first closure specification
• Third-party notices

License

Agent Room source code is licensed under the MIT License. Third-party components retain their own licenses; the generated inventory is published in THIRD_PARTY_NOTICES.md.