RPC

Active contributors: ConradIrwin, maxdeviant

Purpose

crates/rpc and crates/proto define the wire protocol that connects Zed clients to one another and to the collab server. The schema is protobuf-flavored; the transport is a multiplexed message stream over WebSocket (for collab) or SSH (for remote development).

Crates

Crate	Role
crates/proto	Generated protobuf types + manually-curated request/event defs
crates/rpc	Message routing, request/response correlation, peer abstraction
crates/cloud_api_types	REST DTOs for zed.dev + cloud LLM gateway
crates/cloud_api_client	Typed HTTP client for the cloud REST surface
crates/cloud_llm_client	Typed client for the cloud LLM gateway endpoints
crates/client	High-level "Zed client" that drives the editor's collab + cloud

Key abstractions

Type	File	Description
Peer	crates/rpc/src/peer.rs	One end of an RPC connection
Connection	crates/rpc/src/peer.rs	Multiplexed stream over an underlying transport
TypedEnvelope	crates/rpc/src/proto.rs	Strongly-typed wrapper over a protobuf envelope
Request types	crates/proto/proto/...	One file per group (collab, channels, projects, ...)
Server / Client	crates/collab/src/rpc.rs, crates/client/src/client.rs	Application-level wiring

How it works

graph LR
    A[Zed A] <-->|WebSocket| Server[collab::rpc::Server]
    B[Zed B] <-->|WebSocket| Server
    Server --> A
    Server --> B
    A <-->|SSH stream| RS[remote_server]

Message dispatch

Each protobuf message kind has a handler registered on the server (collab::rpc) or client (client). The Peer machinery handles:

• Framing (length-prefixed protobuf).
• Request/response correlation via per-message IDs.
• Backpressure-aware send queues.
• Reconnect with exponential backoff (on the client).

Two domains

There are two related but distinct RPC surfaces:

1. Collab RPC. Messages exchanged between Zed clients and the collab server. This is the channel that powers shared projects, calls, channels, and presence. It's a long-lived WebSocket bound to a user session. Schema lives in crates/proto.
2. Remote-server RPC. Messages exchanged between a local Zed and a remote_server instance. Same protobuf envelope, different transport (an SSH-multiplexed channel handled by crates/remote_connection).

Some message types are reused across both domains (e.g. project + buffer messages).

Versioning

Compatibility relies on additive protobuf changes. Each message has a kind byte. Removing or repurposing kinds is avoided; the schema accumulates rather than churns.

Integration points

• Schema: crates/proto/proto/*.proto (generated to Rust by build scripts).
• Server: crates/collab/src/rpc.rs registers handlers and dispatches.
• Client: crates/client/src/client.rs plus per-feature consumers (crates/call, crates/channel, crates/notifications, …).
• Remote dev: crates/remote_server/src/server.rs registers headless handlers.
• Cloud REST: crates/cloud_api_client for the zed.dev REST surface; crates/cloud_llm_client for the LLM gateway.

Entry points for modification

• Adding a new RPC message — define in crates/proto/proto/*.proto, regenerate, then wire up handlers on both ends.
• New cloud REST endpoint — define in crates/cloud_api_types, expose via crates/cloud_api_client.
• Transport changes — crates/rpc/src/peer.rs for collab, crates/remote_connection/src/transport for SSH.

Related pages

• collab — the main consumer on the server side
• remote_server — the consumer on the remote side
• Collaboration
• Remote development