zai-org/Synapse: A Self-Hosted AI Workspace Where Conversations Are the Runtime

The problem Synapse solves: chat as the collaboration boundary, not a bot's front end

Most self-hosted AI chat stacks put a model behind a text box and call the result a product. Synapse starts from a different premise. The README states that in Synapse a conversation is not a chat log in front of a bot but the runtime boundary: participants, transcript visibility, actor sessions, wakeups and memory handoff are all scoped to it. There is no standalone, API-invoked session, which means you cannot bypass the conversation to call an actor directly.

The intended user is a team that already runs agents and wants them in one room. Four kinds of participants share a thread: workspace members, native actors, bridged remote agents, and external IM identities. A coding agent on your laptop can join as a first-class participant through the remote-agent daemon, keeping its own runtime, tools and model accounts. Eight IM transports, including Feishu, WeChat, WeCom, DingTalk, QQ, Telegram, the WhatsApp Cloud API and WhatsApp via the unofficial web protocol, connect external chats to the same runtime rather than to a separate bot system. That breadth is the pitch: one governed thread instead of five disconnected integrations.

How the runtime works: durable wakeups, reverse MCP, and one grant ledger

The mechanism that holds the design together is the wakeup. An actor's message lands as a durable wakeup for another actor, so multi-agent handoffs happen in the open, inside the same transcript. That is a deliberate contrast with orchestrators that run agents in private loops and post only a summary.

Bridged agents connect over an outbound WebSocket from packages/remote-agent-daemon. The README describes the direction of travel as pull, not push: the bridged agent fetches messages and posts replies through a per-conversation reverse-MCP tool surface, and Synapse does not push unsolicited content to it. When the remote agent needs input or plan approval, a task card lands in the conversation and any eligible participant can answer it.

Authorization is centralized rather than per-integration. Actors, plugins, skills, runtime capabilities, memory spaces and event sources are all managed through a single workspace_resource_grants ledger. Approvals are consume-once: approving replays the exact original call server-side, the model never retypes it, and the one-time grant is consumed after use. That design removes a class of prompt-injection replay, but it also means every new capability has to be modeled as a grant before it can be used at all.

Devices follow the same pattern. Paired desktops, Linux servers and cloud Docker hosts dial out to the control plane, and every operation travels as a signed envelope over the device's own connection. Filesystem, command line, browser (Chrome DevTools) and computer use are exposed as MCP tools, granted per capability and per conversation. Each device also probes and advertises the CLI tools it found locally, so actors work from detected capabilities rather than assumptions.

Installing Synapse and getting a first conversation running

The repository ships a setup script and a docker-compose.yml, and the compose file expects credentials that setup.sh is meant to generate. The postgres service uses the pgvector/pgvector:pg16 image, and the password variable is declared as required with the message that you should run ./setup.sh first.

./setup.sh

After that, the compose file brings up postgres, redis and the api service, with postgres bound to 127.0.0.1:5432 and redis to 127.0.0.1:6379. The README points to deploy.md for deployment details, and the compose file is the concrete entry point.

docker compose up -d --build

For local development without containers, the root package.json exposes separate dev scripts for each part of the system, so you can run the API, the web app and the remote-agent daemon independently.

npm run dev:api
npm run dev:web
npm run dev:daemon

The sandbox runtime is opt-in. The README states it is controlled by SANDBOX_PROVIDER and is off by default, and that the off-box provider requires a self-hosted CubeSandbox endpoint. There are separate compose files for the sandbox variants, docker-compose.sandbox-docker.yml and docker-compose.sandbox-local.yml. A first real use is to start the stack, create a conversation, add a native actor, and watch a second actor wake on the first actor's message. That sequence exercises the core claim of the project rather than a peripheral feature.

Where Synapse is the wrong tool: schema churn, best-effort delivery, and sidecar weight

The README carries a note that Synapse is in an early design and implementation phase, that schemas and runtime contracts can still change quickly, and that backward compatibility for old data is not guaranteed yet. Treat that literally. If you are planning a migration from an existing chat system, or you need a data contract that survives an upgrade, this is the wrong tool for now. The absence of retrieved releases reinforces the point: there is a version number in package.json, but nothing in the repository's release information suggests a stable upgrade path.

Delivery guarantees are uneven. The README says voice notes are transcoded on ingest, and that delivery status reported by IM platforms is best-effort. If your workflow depends on knowing that a WhatsApp or Telegram message was actually delivered, the platform's own reporting is the limit, not Synapse.

Cross-workspace sharing is narrower than the phrase shareable teammates suggests. The README states that sharing covers discovery and rosters today, while conversations and execution stay inside one workspace. A shared actor is a contact, not a remote worker you can dispatch into someone else's thread.

Optional integrations carry real operational weight. The .env.example describes the Xiaohongshu sidecar as heavy, running a headless-browser backend per tenant, with XHS_MAX_TENANT_BACKENDS defaulting to 3 and an idle TTL of 1800 seconds before an inactive tenant backend is torn down. It also notes an SSRF guard in the form of XHS_STORAGE_HOSTS, an allowlist of storage hosts the sidecar may reach for media upload, and that an empty value disables publish-with-media. Those are not settings you turn on casually. The same file marks the mcp-plugins sidecars as overseas-only integrations to leave disabled unless your deployment is meant to reach the relevant external services.

How Synapse differs from Open WebUI and from agent frameworks

Open WebUI is the closest well-known comparison point in the self-hosted chat space: a web interface over one or more model backends, with users and chats as the primary objects. Synapse keeps the web surface, but the object model is inverted. The unit is a conversation with participants and grants, and a standalone API-invoked session does not exist. That difference shows up in practice: in Open WebUI you add a model and chat with it; in Synapse you add an actor to a conversation and it can be woken by another actor's message inside the same transcript.

Agent frameworks such as LangGraph or CrewAI are the other comparison, and the gap is the opposite one. Those libraries give you orchestration inside your own process, with your own storage and your own auth. Synapse gives you the workspace around the orchestration: a grant ledger, paired devices, IM transports, and a remote-agent daemon that lets an agent you already run on a laptop join as a participant. If you want to embed agent logic in an existing service, a framework is the smaller dependency. If you want humans and agents in one governed room with an audit trail of what was approved, Synapse is aimed at that.

Maintenance status, upgrade cost and licence

The repository is not archived, and the last push was on 2026-07-31. That is recent enough that the project is still being worked on, but the README's own early-phase note is the more useful signal for planning: schemas and runtime contracts can change quickly, and old data is not guaranteed to keep working. Budget for reading CHANGELOG.md before each upgrade, since the repository maintains English, Chinese and Spanish changelogs, and for the possibility that a schema change requires a data migration you have to write yourself.

The build is not trivial. The root build script compiles helper binaries first (build:cua-helper and build:fs-helper), then builds device-protocol, shared, the chat worker, device-runtime, device-sdk, api, remote-agent-daemon and web-next in sequence. There is also a postinstall step that applies patches, and a prepare script that points git at .githooks. A CI pipeline that skips the helper builds will fail before it reaches the TypeScript.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. Note that the .env.example mentions the Bilibili sidecar wraps a GPL-3.0 library, so that particular optional component carries different obligations from the rest of the repository. Whether that affects your distribution is a question for your own counsel, not something the README settles.

Editorial conclusion

Adopt Synapse if you need a self-hosted place where humans, native actors, bridged coding agents and IM identities share one governed thread, and you can accept schema churn. Do not adopt it if you need a stable data contract or a single-bot chat UI, because the README states backward compatibility for old data is not guaranteed. Before committing, read deploy.md, run ./setup.sh against a throwaway database, and check whether the sandbox provider you want is actually supported in your environment.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. zai-org/Synapse on GitHub