collab

Active contributors: ConradIrwin, maxdeviant, mikayla-maki

Purpose

crates/collab is the backend service that powers Zed's multiplayer features: channels, calls, presence, shared projects, signaling for LiveKit audio, and parts of the cloud-LLM gateway. It is a separate Rust binary deployed by Zed Industries, not bundled with the editor. The license is AGPL.

The deployed instances live at:

• Staging: https://staging-collab.zed.dev
• Production: https://collab.zed.dev

Both run on Kubernetes in Digital Ocean.

Directory layout

crates/collab/
├── Cargo.toml
├── README.md           # Local-dev setup (Postgres, foreman, zed-local)
├── k8s/                # Kubernetes manifests
├── migrations/         # Postgres migrations (production)
├── migrations.sqlite/  # SQLite migrations (tests)
├── seed/               # Seed data for local dev
├── seed.default.json   # Default admin GitHub logins
├── src/
│   ├── main.rs         # Binary entry point (subcommands: serve, …)
│   ├── lib.rs          # Library surface
│   ├── api/            # HTTP API handlers
│   ├── api.rs          # API root
│   ├── auth.rs         # GitHub OAuth + token auth
│   ├── bin/            # Subcommand entry points
│   ├── db/             # Postgres data access
│   ├── db.rs           # DB module root
│   ├── env.rs          # Env-var configuration
│   ├── errors.rs       # Error types
│   ├── executor.rs     # Tokio runtime helpers
│   ├── completion.rs   # LLM completion proxy (cloud gateway)
│   ├── rpc/            # WebSocket RPC handlers
│   ├── rpc.rs          # RPC module root
│   └── seed.rs         # Local-dev seeding
└── tests/              # End-to-end tests against a real Postgres

Key abstractions

Type / module	File	Description
Server	crates/collab/src/rpc.rs	The WebSocket server holding live connections
Database	crates/collab/src/db.rs	Postgres data access; SQLx-based
Config	crates/collab/src/env.rs	Environment-variable-driven configuration
serve	crates/collab/src/main.rs	Top-level subcommand to run the API + RPC servers
HTTP routes	crates/collab/src/api/	REST endpoints (users, billing, channels, etc.)
RPC handlers	crates/collab/src/rpc/	Per-message handlers, message dispatch

How it works

graph TD
    Z[Zed client] -->|WebSocket| RPC[rpc::Server]
    Z -->|HTTPS| API[api::routes]
    RPC --> DB[(Postgres)]
    API --> DB
    RPC -->|signaling| LK[LiveKit]
    API -->|completions proxy| LLM[LLM providers]
    GH[GitHub OAuth] --> AUTH[auth.rs]
    Z --> AUTH

• Clients authenticate via crates/collab's OAuth flow (GitHub-based) and receive a server-issued token.
• Live RPC traffic flows over a single WebSocket per client, framed with the protobuf schema in crates/proto.
• LiveKit signaling for voice channels uses the crates/livekit_api SDK; tokens are minted by collab.
• The cloud LLM gateway in completion.rs proxies requests to upstream providers; metering and rate-limits are enforced server-side.

Integration points

• Inbound: Zed clients (crates/client, crates/rpc), the Zed website (REST endpoints).
• Outbound: Postgres, LiveKit, upstream LLM providers.
• Schema: crates/proto is the single source of truth for RPC messages — both collab and client depend on it.
• Local dev: script/bootstrap (in crates/collab) sets up Postgres and seeds users; foreman start runs collab + LiveKit dev server; script/zed-local -2 spawns multiple Zed clients connected to the local server.

Deployment

Triggered by pushing to the collab-staging or collab-production tags. Helpful workflows:

• .github/workflows/deploy_collab.yml
• .github/workflows/bump_collab_staging.yml
• script/deploy-collab
• script/digital-ocean-db.sh

The staging environment also doubles as a load-test target via script/collab-flamegraph.

Entry points for modification

• Adding a new RPC message — define it in crates/proto, add a handler under crates/collab/src/rpc/, and consume it in crates/client or wherever the client side lives.
• Adding a new HTTP endpoint — crates/collab/src/api/.
• Migrating the schema — add a new file in crates/collab/migrations/. SQLite-equivalent migration goes in migrations.sqlite/ for tests.
• Tweaking auth — crates/collab/src/auth.rs.

Related pages

• Collaboration — the user-facing feature this service powers
• RPC — the protobuf schema shared with clients