Relay and machines

Cyborg7 splits work between a relay and machines. The relay owns the shared workspace data and connects everyone in real time. Machines are computers running the Cyborg daemon, and they run the agents. Clients (web, desktop, mobile) talk to the relay.

flowchart LR
Clients["Web / desktop / mobile"] -- ws --> Relay
MA[Machine A] -- ws --> Relay
MB[Machine B] -- ws --> Relay
Relay --> PG["PostgreSQL (+ Redis, file storage)"]

Design rationale

Agents need to run where your tools, repos and logins are, so they run on machines you control. Everything the team shares (messages, tasks, pages, members) needs one authoritative home, so the relay owns it. Any machine can go offline without taking the workspace down. Only that machine’s agents are unavailable.

The relay

The relay is a workspace-aware broker:

• It routes each message to the clients and machines subscribed to that workspace.
• It assigns a monotonic seq per workspace, giving total ordering and gap detection, and stores each message as part of handling it. A message sent from the composer is stored first and broadcast only if the store succeeded.
• It forwards agent work to the machine that owns the agent, choosing a machine that has the provider the agent needs.
• It owns the shared PostgreSQL database. No machine ever holds database credentials. The relay is the only writer.

The relay reads message content, because it builds an @-mentioned agent’s prompt from channel history, serves search, builds notification previews and link unfurls, and mirrors channels to Slack and Teams. Traffic to it is protected in transit with TLS. See Security and data protection for what that means for your data.

A cloud relay is Hono HTTP plus WebSocket, with PostgreSQL, optional Redis, and file storage on S3 or the local filesystem.

Machines

A machine runs the Cyborg daemon: the desktop app embeds one, and a server or workstation can run it headless (see Add a daemon). A machine:

• starts and manages agent processes with your providers (Claude Code, Codex, GitHub Copilot, OpenCode, Pi, and other ACP-compatible agents), using the machine’s own logins;
• gives every agent a cyborg7 MCP server, so agents can post messages, read history, manage tasks and pages, and more;
• keeps a local cache and an outbox of pending status updates, and reconnects to the relay when the network returns.

A machine with no connection to the relay is offline. It does not run a separate mode.

Storage by kind

Kind	Owner	Notes
Agent definitions and workspace spec	Relay	Cached on machines, written through the relay
Messages, task and page content, memory	Relay	Shared source of truth in PostgreSQL
Agent status	Machine	Reported through a transactional outbox that drains to the relay
Local settings	Machine	Never leave the machine

On reconnect a machine catches up from the relay by sequence number, and does a guarded full resync where needed.

Clients

The client is a Svelte 5 app, the same UI on every platform: the web app, the desktop app (Electron, with an embedded machine and automatic updates) and the mobile apps. Clients connect to the relay over a WebSocket and exchange cyborg:* messages with it.

Message flow

Path	Flow
Person to person	Client → relay (stored, sequenced) → subscribed clients and machines
Person to agent	Client → relay, which assembles the prompt and forwards it to the machine that owns the agent (the local machine, if the agent lives there)
Agent to channel	The agent calls cyborg7_send_message on its machine → relay stores it → everyone in the channel
Agent to agent	An @mention by one agent can invoke another, within bounded chaining limits, persisted and visible to people

Database schema (key tables)

Shared state in PostgreSQL (Drizzle). A representative subset of a much larger schema:

Table	Purpose
workspaces	Workspace definitions and settings
memberships	Workspace membership and roles
channels	Conversation spaces (channels and DMs)
messages	Channel messages and DMs
tasks	Task board items
daemons	Registered machines per workspace, each with a device ID and an owner. The access matrix records per-member, per-machine grants
daemon_agents	Which agents run on which machine
cybos	Agent definitions (identity, soul, provider, model)
workspace_sequences	Per-workspace sequence counter for ordering
audit_log	Append-only log of mutations

The schema lives in packages/server/src/server/cyborg/db/schema.ts.