Installation

Installation

← Wiki home

This guide installs the Linux host components: the maintained patched Zed build, the local gateway, and Zed tasks. Pairing comes later.

Requirements

• A Linux workstation supported by Zed.
• Git, Python 3, Rust, and Cargo.
• The Zed Linux build dependencies.
• A model already working in desktop Zed.
• A private route that can carry trusted HTTPS. Tailscale with MagicDNS is the recommended first setup.
• Enough disk space for a Zed source checkout and build artifacts.

The first Zed build can take a while. ZedLink does not download model weights or copy model credentials.

1. Clone the repository

git clone https://github.com/tjnull/zedlink.git
cd zedlink

Do not place secrets, certificates, or a Zed source checkout inside the repository. Generated state belongs under the private paths selected by setup.

2. Run guided setup

bash tools/setup_zed_ide.sh

The guided flow can:

1. create or update the ignored zed-source/ checkout from the maintained Zed fork;
2. build patched Zed and the Rust gateway;
3. save the selected project and private connection profile;
4. install global Zed tasks without replacing unrelated tasks; and
5. install the ZedLink — Patched Zed application launcher.

For an unattended update after configuration:

bash tools/setup_zed_ide.sh --yes

Run bash tools/setup_zed_ide.sh --help before using skip options. The installer preserves an existing valid configuration and does not modify Zed's model provider, endpoint, name, or credentials.

3. Use the Zed task picker

Open this repository in Zed, press Ctrl+Shift+P, choose task: spawn, and search for ZedLink.

The main setup tasks are:

Task	Purpose
ZedLink: Set up this project	Configure the worktree currently open in patched Zed
ZedLink: Guided setup / update	Run the complete installer interactively
ZedLink: Install / build	Update and build patched Zed and the gateway
ZedLink: Configure	Change project, route, TLS, or profile settings
ZedLink: Diagnose setup	Print a read-only health report
ZedLink: Repair setup	Restore managed settings, tasks, launcher, and private directories
ZedLink: Status	Show build, bridge, gateway, route, and device state

If the tasks are missing, confirm that the ZedLink repository is the open worktree and rerun guided setup.

4. Launch the correct Zed build

Open ZedLink — Patched Zed from the application menu. The official Zed release and the patched development build are separate applications.

Application	Typical executable	ZedLink native bridge
Official Zed	~/.local/zed.app/libexec/zed-editor	No
ZedLink patched Zed	zed-source/target/debug/zed	Yes

If the launcher is missing, run ZedLink: Install patched Zed launcher. You can also run ZedLink: Start patched Zed from the task picker.

5. Verify the installation

Run ZedLink: Status, then ZedLink: Diagnose setup. Confirm that:

• the pinned patched Zed executable exists;
• the gateway executable exists;
• the project and private state directory are the intended paths;
• the native socket and connection profile are recognized; and
• no certificate or key is stored inside the repository.

Continue with Configuration.

Updating

Pull the repository, then rerun guided setup:

git pull --ff-only
bash tools/setup_zed_ide.sh --yes

Finish active Agent work before restarting patched Zed. Restart the gateway after a web or gateway change. Rebuild and reinstall native mobile apps separately; a gateway update cannot update an APK or iOS app.

Removing local integration

Use the manager's explicit removal actions rather than deleting configuration piecemeal:

python3 tools/zedlink_manager.py remove-launcher
python3 tools/zedlink_manager.py remove-cli
bash tools/setup_zed_ide.sh --remove-global-tasks

Review saved device, route, and private state before deleting it. Removing the ignored zed-source/ directory only recovers build space; the next install must clone and compile Zed again.