AgentRoom server and macOS app

AgentRoom runs coding-agent sessions on a Mac and exposes them to clients over
REST and WebSocket. The backend registers local folders as workspaces, starts
Codex, Claude Code, DeepSeek Harness, Cursor, or an external ACP agent inside
them, owns session state, and streams typed events. The macOS app is the
operator console: it configures runners, keeps secrets in Keychain, registers
workspaces, starts and supervises the backend, and shows diagnostics.

This repository holds the backend, the macOS app, and the Swift client library
the Apple apps compile. It does not hold the visionOS app. That app is the main
session client (threads, editor, source control, spatial diagrams) and is not
open source yet. The Mac app's Threads view supervises sessions and can stop a
turn, but it does not send prompts. With this repository alone you run the
backend and drive turns through its API with curl or a client of your own;
Local Mac server walks through that.

flowchart TB
    client["your client"]

    subgraph mac["the operator's Mac"]
        operator["macOS operator app"]
        backend["Fastify backend"]
        workspaces["registered local workspaces"]
        agents["Codex, Claude Code, DeepSeek, Cursor, or ACP agent"]

        operator -->|launches, supervises, REST| backend
        backend -->|registers| workspaces
        backend -->|starts inside a workspace| agents
    end

    client -->|REST + WebSocket| backend

What is here

The backend supports persistent agent threads with live assistant text,
reasoning, tool activity, plans, diffs, token usage, and permission events;
explicit file and directory context, runner-native skill discovery, and PNG,
JPEG, or WebP turn attachments; bounded workspace browsing, quick open, literal
content search, UTF-8 file writes, single-folder creation, same-parent entry
rename, same-workspace
entry move and copy, and bounded
file/folder deletion; Git status, branches,
staging, discard, commit, fetch, fast-forward pull, push, and branch creation
through fixed operations; an optional terminal that opens a real shell on the
Mac (off by default); an optional closed backend protocol for Mac-hosted
SourceKit-LSP, bundled TypeScript/JavaScript and Python, and operator-installed
Rust, Go, Java, Kotlin, and C# semantics, plus separately gated external LSP
descriptors (off by default); live SVG and Mermaid
sketches; and composition of
*.diagram.json and *.scene.json spatial documents with their human override
layers.

Download

Each versioned release on the Releases page
carries AgentRoom-<version>-arm64.dmg,
AgentRoom-<version>-release.json, and SHA256SUMS.txt. Update-enabled releases
also carry appcast.xml. The
manifest records the backend/API compatibility policy used by AgentRoom
clients. Every attached artifact is covered by the checksums. The app
is signed with a Developer ID certificate and notarized by Apple, so it opens
like any other downloaded Mac app. Apple Silicon only.

Verify the download before opening it:

shasum -a 256 -c SHA256SUMS.txt

Open the DMG, drag AgentRoom.app to Applications, and launch it. The app
bundles its own Node.js runtime and the compiled backend, so nothing else has to
be installed to start the backend. You still need at least one runner: Codex
(set its executable path in the app), Claude Code (sign in with claude login
as the Mac user), Cursor (run the sign-in command in
Signing in to Cursor; a Cursor
Pro plan or better is required), or DeepSeek Harness (see the
DeepSeek runner guide).

Signed stable release builds embed the Sparkle release key and check the fixed
latest-stable appcast once a day. Sparkle still asks before installation. Source
and unsigned builds contain no key or feed and make no update request.

Release candidates are isolated from that stable feed. A signed
vX.Y.Z-rc.N build checks the rolling prerelease-only rc appcast, whose
download still points to the exact versioned RC release. To test updating,
manually install RC.1, have a maintainer publish RC.2 through the private
release workflow, then use Check for Updates… in RC.1. Stable installations
never query the RC appcast.

Existing stable installations from before this policy change cannot discover
the first updater-enabled stable release because they contain no Sparkle key.
Install that release manually once; later stable releases update through the
stable feed.

Build from source

Requirements:

• macOS 14 or later to run the app; Xcode 26 to build it.
• Node.js 24 LTS or newer and pnpm 9.15.4 (npx pnpm works without a global
  install).
• XcodeGen for the Mac project.

Backend:

pnpm install
cp .env.example .env

Set up a runner in .env. A direct Codex setup needs at least an absolute
executable path:

CODEX_EXECUTABLE=/absolute/path/to/codex

Claude Code uses the Mac user's existing claude login. Cursor's SDK is
bundled; pnpm --filter @agentroom/backend cursor:login completes the web
sign-in it reads. Create a bearer token before connecting another device:

npx pnpm --filter @agentroom/backend auth:init

Run in development (port 8787, debug page at http://localhost:8787, health
check at /health):

pnpm dev

Or compiled:

pnpm --filter @agentroom/backend build
pnpm --filter @agentroom/backend start

Mac app (build the backend first; development builds of the app find
apps/backend/dist/index.js in this checkout):

pnpm --filter @agentroom/backend build
cd apps/macos
xcodegen generate
open AgentRoomMac.xcodeproj

Run the AgentRoomMac scheme. The generated Xcode project is not source; edit
apps/macos/project.yml and regenerate. See
apps/macos/README.md for what the app does and how it
locates the backend.

Local DMG:

npx pnpm dist:macos

This writes build/distribution/macos/AgentRoom.app and AgentRoom.dmg. The
script copies the Node runtime it finds on your machine unless
AGENTROOM_NODE_RUNTIME_DIR points at a full Node.js macOS distribution, and it
signs and notarizes only when AGENTROOM_CODESIGN_IDENTITY and the notary
variables in scripts/package-macos.mjs are set.
npx pnpm install:macos replaces /Applications/AgentRoom.app with that build.

Before you change anything, make sure this passes:

pnpm typecheck
pnpm --filter @agentroom/backend build
pnpm test

Configuration and trust

Startup values and secrets come from the environment or the Mac app's Keychain
storage: the bearer token, executable paths, bind address, storage locations.
Preferences and trust settings live in $AGENTROOM_HOME/config/settings.json;
the Mac app writes that file directly and clients edit it through
GET/PATCH /api/config. An environment value wins over the file and locks
that key, and managed changes apply after a backend restart. The annotated
.env.example lists every setting; the
API reference documents the managed settings response and
patch contract.

Agent threads are stored under the state directory (STATE_DIR/sessions/,
beside the audit log and attachments) and survive a backend restart, a crash,
and an app update. The next turn on a restored thread continues the same
native conversation; if the runner cannot resume it, the thread says so in a
system message rather than continuing under the old name. Deleting a thread
is the only way its record goes away.

Registered does not mean sandboxed. Read these before pointing AgentRoom at a
repository you did not write:

• Codex loads the workspace's AGENTS.md, repository skills, and
  .codex/config.toml, including configured MCP servers and hooks.
• Claude Code can load the workspace's project settings, hooks, MCP servers,
  skills, and CLAUDE.md. Its default bypassPermissions mode is not confined
  to the registered folder.
• A DeepSeek turn is bounded by the operator-supplied Cordis composition, which
  AgentRoom cannot inspect.
• A Cursor turn is sandboxed by default, and that sandbox bounds writes (the
  workspace and /private/tmp) and network egress, not reads. It loads the
  workspace's .cursor/hooks.json, .cursor/mcp.json, rules, and skills
  unless CURSOR_LOAD_WORKSPACE_SETTINGS is off.
• The optional terminal is off by default. On, it is a real shell on the Mac,
  unsandboxed after launch.
• Editor language services are off by default. Their processes may inspect SDKs,
  language environments, project state, or plugins and may invoke ecosystem
  build tools, so enable them only for trusted registered projects. Optional
  Rust, Go, Java, Kotlin, and C# servers require absolute environment-only
  executable paths; the backend never searches PATH for them. External LSP
  descriptors require a second default-off gate, use fixed argv, and cannot
  shadow a built-in language id. A stalled language server cannot retain
  unbounded editor updates: queued input is capped at 4 MiB per child.
• The backend binds to the LAN by default. Set AUTH_TOKEN before connecting a
  second device or enabling the terminal or editor language services.

Workspace reads stay registered-folder-only, bounded, symlink-checked, and
secret-name filtered. The one client write is a bounded UTF-8 file endpoint with
an optimistic lock. Git routes accept fixed operations, not command strings. The
full posture, including known gaps, is
Trust and safety.

Ships with Claude Code and the Cursor SDK

The DMG bundles the Claude Agent SDK, which carries an unmodified Claude Code
binary. AgentRoom starts it as published by Anthropic, and each person signs in
with their own claude login; by default AgentRoom strips Anthropic credentials
from the child it spawns and intermediates no usage. Use of that binary is
governed by
Anthropic's terms.

The DMG also bundles the Cursor SDK and its Anysphere-signed helper binaries,
unmodified. Each person signs in with their own Cursor account through the
SDK's web login, on their own plan (Cursor Pro or better); AgentRoom holds no
Cursor credential and intermediates no usage. Use of the SDK is governed by
Cursor's Terms of Service.

Everything else the DMG bundles is listed in
THIRD_PARTY_NOTICES.md.

This repository is a mirror

Development happens in a private monorepo that also holds the visionOS app. A
workflow there publishes the paths in this repository after each change to its
main, as one commit per sync whose Source-Commit: trailer names the upstream
commit. Nobody pushes here by hand.

Issues are welcome. Pull requests are welcome as proposals: a maintainer reviews
them, ports the change upstream, and closes the PR with a pointer to the sync
commit it arrived in. See CONTRIBUTING.md for the details
and SECURITY.md for reporting vulnerabilities.

Some documents under docs/ link to visionOS client documents that are not in
this repository. Those links point into the private tree.

Documentation

Start with the documentation index, or go directly to:

• Architecture
• API
• macOS client
• Trust and safety
• Runner architecture and maintenance

There is no separate agent guidance file in this tree; the documents above,
starting with Trust and safety, are the
rules for anyone working here, person or agent.

License

MIT. See LICENSE.