Troubleshooting

"Unable to connect to the host"

Desktop shows Connecting to the daemon…, then Unable to connect to the daemon ({url}). Run {command} first. — the host (the LinkCode daemon) it's looking for isn't answering.

Two likely causes:

• No host is running yet. Follow quickstart to start one — the in-app message currently points at a raw developer command from a source checkout, which only makes sense if that's how you started your host.
• A host is running, but at a different URL than the client expects. Open Settings → Connection, check the "Daemon URL" field (leave it empty to auto-discover, or enter the correct URL), and save to reconnect.

Host refuses to start: "already running"

If you try to start a second host, it exits immediately with [linkcode/daemon] already running (pid {pid}) at {url} (or, if it got as far as probing ports, another linkcode daemon (pid {pid}) is already listening at {url}). Only one host runs per machine — a second one would split the same local database. Point your client at the existing host instead of starting another one, or stop the existing process first if you actually meant to restart it.

Port already in use

The host listens on port 19523 by default and hunts upward (19524, 19525, … up to 19532) if something else holds it. If every port in that range is taken, it fails with no free port for socket.io in 19523–19532. Clients don't need to know which port won the hunt — they discover the real URL automatically from ~/.linkcode/runtime.json (see Local data).

Terminals unavailable

Opening a terminal fails with pty sidecar not configured: terminals are unavailable on this host. This is expected in the packaged desktop build today — the terminal's sidecar process isn't bundled with releases yet. It works when you run the host from source with the sidecar built and its path configured. See panels and known limitations.

A Claude Code turn ends instantly with no output

This is a known issue: if Claude Code's credentials are expired or invalid, LinkCode currently shows a normal-looking, empty turn instead of an error — nothing happens and nothing explains why. Re-authenticate by running claude in a terminal and signing in again, or make sure a valid API key is set in the environment the host runs in. (The in-app Agents settings screen for entering an API key isn't usable on desktop yet.)

Pasted images disappear from the prompt

This is expected today — images and other non-text attachments aren't forwarded to any agent yet. See known limitations.

OpenCode: "failed to start server"

OpenCode fails to start a thread with an error like opencode: failed to start server (...). OpenCode is the one agent that isn't bundled with LinkCode — you need the opencode CLI installed and visible on the PATH of the process running your host. See OpenCode for setup.

macOS Gatekeeper / Windows SmartScreen

LinkCode's desktop builds are signed and notarized (macOS) or signed via Azure Trusted Signing (Windows). You shouldn't see a Gatekeeper or SmartScreen warning on a properly downloaded release build. If you do, make sure you downloaded the installer directly from a LinkCode GitHub release rather than a mirrored copy.

Where are the logs?

There's no log file yet. The host prints everything to the stdout/stderr of whatever process started it — if you started it yourself from a terminal (see quickstart), that terminal window is where your logs are.