Troubleshooting

Start with:

link-host doctor

It checks the computer's identity, the running service, and what the desktop needs. The app's Check connection (in the computer's menu) runs each step of a connection and names the one that failed.

Installing

Link Host requires systemd user services

The Linux build runs as a systemd user service. Distributions without systemd (Alpine, Void with runit) aren't supported yet.

OpenSSH is not installed (sshd was not found)

Link's SSH server is the system's OpenSSH server program, started as you. Install your distribution's OpenSSH server package (openssh-server on Debian, Ubuntu and Fedora; openssh on Arch), then run link-host ssh setup.

link-host: command not found

Add ~/.local/bin to your PATH, or run ~/.local/bin/link-host. The phone finds it either way.

Pairing

run 'link-host ssh setup' as your normal user, without sudo

Link's SSH server runs as your account. Run setup without sudo.

could not choose a network address

The computer has several addresses and setup can't tell which the phone should use. Pass one: link-host ssh setup --host 192.168.1.20.

The firewall blocks port 2222

On distributions whose firewall drops incoming connections (Arch's default nftables, for one), setup prints the single command that allows port 2222. Only direct connections on your network need it.

The code expired

Codes last 10 minutes. Run link-host ssh setup again.

Connecting

"No direct path from this network"

Rendezvous couldn't open a direct path between the phone's network and the computer's; some mobile carriers and office networks prevent it. Try another network, or deploy your own relay and pair through it.

"This computer's SSH key changed"

The computer presented a different key from the one the phone trusted. If you reinstalled the computer or reset Link's SSH server, open Check connection in the app, compare the new key with the one you expect, and replace it there. If you didn't change anything, don't: something may be impersonating your computer.

The phone signs in nowhere after uninstalling

Uninstalling removes Link's SSH server and its keys. Reinstall and pair again.

Agents

An agent isn't listed

Link looks for each agent's command on the PATH and in the usual user install folders. If yours lives elsewhere, make sure your login shell's PATH includes it: Link reads that too.

A Claude session in a terminal doesn't take messages from the phone

It wasn't started with Link's channel. See Claude in a terminal.

Desktop

FFmpeg missing (desktop capture unavailable)

Install FFmpeg.

Wayland capture needs GStreamer with its PipeWire plugin

Install GStreamer's PipeWire plugin (gst-plugin-pipewire on Arch, gstreamer1.0-pipewire on Debian and Ubuntu).

The phone waits for "Allow" forever

The first desktop session on Wayland shows a sharing dialog on the computer itself. Someone at the computer must choose Allow once.