Remote development

Active contributors: ConradIrwin, kubkon, mikayla-maki

Purpose

Open a project that lives on another machine and edit it as if it were local. Zed handles transport (SSH by default), uploads / runs the headless server, and proxies the entire Project over an RPC channel. Language servers, debug adapters, and terminals all run on the remote host.

Crates

Crate	Role
crates/remote	Local-side glue: connection state, settings, UI affordances
crates/remote_connection	Transport layer (SSH transport, identity, multiplexing)
crates/remote_server	The headless server-side editor (separate binary)
crates/recent_projects	UI for RemoteSettings and the recent-projects picker
crates/dev_container	Devcontainer-aware remote setup

How it works

sequenceDiagram
    participant L as Local Zed
    participant SSH as SSH transport
    participant R as remote_server (remote host)
    participant P as Headless Project

    L->>SSH: connect (host, user, key)
    SSH-->>L: open multiplexed channel
    L->>SSH: upload remote_server (if missing)
    L->>R: spawn remote_server --project <path>
    R->>P: HeadlessProject::new(path)
    L->>R: ProjectFollow(...)
    R-->>L: project snapshot
    L->>R: open buffer foo.rs
    R-->>L: buffer + diagnostics

Connection establishment

crates/remote_connection handles:

• Reading SSH config (~/.ssh/config).
• Authentication (key-based, ssh-agent, password fallback via crates/askpass).
• Multiplexing the wire so file ops, LSP traffic, terminal data, and DAP traffic all share one TCP connection.
• Reconnect with state preservation when the link blips.

Uploading the server

If the remote host doesn't already have a matching remote_server binary, the local client uploads one targeted at the remote OS/arch. Versions must match the local Zed; mismatch triggers a re-upload.

Headless project

HeadlessProject (crates/remote_server/src/headless_project.rs) mirrors the local Project minus GPUI views. Operations from the local client become RPC calls on the headless project; results stream back.

Devcontainers

crates/dev_container adds devcontainer awareness — Zed can spin up a container on the remote, open a project inside it, and behave as if connecting to the container directly.

Settings

Remote-specific settings (host preferences, env, port forwarding) are managed through crates/recent_projects::RemoteSettings. They layer over project settings via the regular SettingsStore.

Entry points for modification

• New transport — crates/remote_connection/src/transport/.
• New RPC operation needed for remote — crates/proto, then handle in crates/remote_server (server) and crates/remote (client).
• Devcontainer changes — crates/dev_container/src/.
• Connection UX — crates/remote/src/... plus crates/recent_projects.

Related pages

• remote_server
• Project
• RPC