remote_server

Active contributors: ConradIrwin, kubkon, mikayla-maki

Purpose

crates/remote_server is the headless server-side editor that runs on a remote development host. It mirrors enough of the local Project, Worktree, and language-server stack to let a local Zed drive a full editing session over an SSH-multiplexed RPC channel. Together with crates/remote and crates/remote_connection on the client side, it is the foundation of Remote development.

Directory layout

crates/remote_server/
├── Cargo.toml
└── src/
    ├── main.rs                  # Binary entry point
    ├── server.rs                # Server loop + RPC dispatch
    ├── headless_project.rs      # The "headless" Project that lives on the server
    ├── remote_editing_tests.rs  # Integration tests against a fake remote
    └── windows.rs               # Windows-specific platform glue

Key abstractions

Type	File	Description
pub fn main()	crates/remote_server/src/main.rs	Process entry. Parses args, sets up logging, runs server
RemoteServer	crates/remote_server/src/server.rs	RPC server, dispatch, lifecycle
HeadlessProject	crates/remote_server/src/headless_project.rs	Project + Worktree without a UI

How it works

graph LR
    user[Local Zed] -->|SSH transport| transport[remote_connection::Transport]
    transport --> rpc[Multiplexed RPC]
    rpc --> rs[remote_server]
    rs --> hp[HeadlessProject]
    hp --> wt[Worktree]
    hp --> ls[LSP servers on host]
    hp --> dap[DAP adapters on host]
    hp --> term[Terminal sessions]

The local client opens an SSH connection (or other transport) to the remote, uploads the remote_server binary if needed, and exec's it. Once running, both ends speak the same protobuf RPC (defined in crates/proto) over the multiplexed channel.

The HeadlessProject differs from the local Project in:

• It has no GPUI views — it's pure model.
• It exposes RPC handlers for every operation the local UI needs.
• It runs language servers and debug adapters in its own process tree, so the toolchain matches the remote host's.
• File watching uses local notify mechanisms on the remote, surfaced via the same Worktree abstraction.

Integration points

• Talks to: the local zed via crates/remote_connection's SSH transport (crates/remote_connection/src/transport).
• Spawns on remote: language servers, debug adapters, terminals, the Node sidecar.
• Shares: the protobuf schema with crates/proto, so the same message types route between local and remote.

Entry points for modification

• Adding a new RPC operation — define it in crates/proto, handle it in crates/remote_server/src/server.rs, and call it from crates/remote on the client side.
• Improving SSH transport behaviour — crates/remote_connection/src/transport.rs.
• Adjusting headless behaviour — crates/remote_server/src/headless_project.rs.

Related pages

• Remote development — user-facing feature
• Project — the model this mirrors