Skip to main content

Troubleshooting

Companion tray says "OFFLINE"​

The agent isn't responding to the local /healthz probe. Steps:

  1. Open Preferences, then the Agent panel. Confirm Status: Stopped, and try Restart.
  2. Or from a terminal: locai status to see what's going on, then locai restart.
  3. Alternatively, restart the service manually:
    • macOS: launchctl kickstart -k gui/$(id -u)/uk.co.locai.link.companion
    • Linux: systemctl --user restart locai-link-companion.service
  4. Check the logs (Preferences, Advanced, Logs). Common issues: model file corrupted mid-download (delete the partial and redownload), or the Zenoh transport can't reach the router (firewall; see the next section).

Network panel says "Disconnected"​

Agent is up but can't reach Locai Control's Zenoh router. Common causes:

  • Corporate firewall blocking outbound TCP 7448. The port Zenoh uses. Ask your network admin to allow outbound TCP to zenoh.locai.co.uk:7448.
  • TLS interception (Zscaler, corporate proxy, some antivirus). The Zenoh TLS handshake fails because a middlebox is re-signing certificates. Requires the middlebox's CA to be trusted or an exception for zenoh.locai.co.uk.
  • VPN in the way. Try disconnecting the VPN and see if Network flips to Connected.

Test connectivity directly:

nc -zv zenoh.locai.co.uk 7448

succeeded! means the firewall isn't blocking; it's likely a TLS or router-side issue. Connection refused or a hang means a firewall.

First-run setup fails at registration​

  • "Invalid registration key". The key is used or expired. Click Retry to mint a fresh one (or, on a headless device, generate a new key in the Register Device dialog).
  • "Registration failed: network". See the firewall notes above. api.locai.co.uk on HTTPS (443) needs to be reachable.

Companion doesn't appear in the menu bar after install​

macOS:

  1. Confirm the service is loaded: launchctl list | grep locai. You should see one entry: uk.co.locai.link.companion.
  2. If missing, try starting manually: launchctl kickstart -k gui/$(id -u)/uk.co.locai.link.companion (or locai start).
  3. If the process starts but no tray icon appears, log out and back in. macOS occasionally needs a fresh session to attach the icon.

Linux:

  1. systemctl --user status locai-link-companion.service should show active (running).
  2. Confirm your desktop environment supports StatusNotifier / SNI tray icons. GNOME needs the AppIndicator extension; KDE Plasma has it built-in. Sway and i3 don't have a tray by default (you'll need waybar or polybar with tray support).

Model download is stuck at 0%​

  • Open Preferences, then Models. Find the row and click Cancel.
  • Wait a second, then re-trigger the deploy from Locai Control. First-attempt hangs are usually a transient network issue or the runtime not being fully warm; retrying almost always works.
  • If a "Queued" row has been sitting for over 5 minutes, the runtime automatically flips it to Failed (Control's dispatch was likely lost). Cancel and redeploy.

Device appears offline in Control right after starting​

The device reports online only once its command channel is fully ready. On slow networks this can take up to roughly 5 seconds after the agent starts. If the device remains offline for longer, check your network connection and restart the agent from the companion's Preferences.

Duplicate companion icon in the tray​

Locai Link includes a single-instance guard (since 1.2.0) that prevents a second companion from opening: launching the app again focuses the existing window. If you still see duplicate icons, log out and back in to clear the stale process.

"Device shows Version unknown in Control"​

Fixed in v1.0.19+. If you're on an older release, restart the agent (Preferences, Advanced, Restart, or launchctl kickstart -k … as above) and Control picks up the version from the next heartbeat.

Diagnostics for support​

When reporting an issue, attach the log file(s) — the quickest way to find them is Preferences → Advanced → Logs:

  • macOS (desktop): /Library/Locai/logs/link.*.log
  • Linux (desktop): ~/.local/share/locai/logs/link.*.log
  • Headless installs: logs/service.log under the install root on macOS and Windows; on Linux, journalctl --user -u locai-link-headless.service

Also include the output of:

curl -s http://127.0.0.1:20505/healthz | jq .   # agent health snapshot
curl -s http://127.0.0.1:20505/models | jq .    # models list

Both endpoints are loopback-only; nothing from outside your machine can reach them.