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.
  2. Try Restart from the Advanced section (if visible).
  3. Alternatively, restart the LaunchAgent manually:
    • macOS: launchctl kickstart -k gui/$(id -u)/uk.co.locai.link.agent
    • Linux: systemctl --user restart locai-link-agent.service
  4. Check the log file (Preferences, Advanced, Log file). 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.

Setup Assistant fails at registration​

  • "Invalid registration key". The key is used or expired. Ask your admin to mint a new one and click Retry.
  • "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 LaunchAgent is loaded: launchctl list | grep locai. You should see two entries: uk.co.locai.link.agent and uk.co.locai.link.companion.
  2. If missing, try starting manually: launchctl kickstart -k gui/$(id -u)/uk.co.locai.link.companion.
  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 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) at:

  • macOS: /Library/Locai/logs/agent.stdout.log and /Library/Locai/logs/companion.stdout.log
  • Linux: ~/.local/share/locai/logs/agent.stdout.log and ~/.local/share/locai/logs/companion.stdout.log

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.