Troubleshooting

Start with two commands - they answer most questions:

opencompanion status            # pairings, connected CLIs, and each CLI's auth health
opencompanion service status    # whether the always-on service is installed and running

The device shows offline in the app

The app marks a device online only while its daemon is polling (within a 90-second presence window). Offline means the daemon is not reaching the app. Check, in order:

1. Is the service running? opencompanion service status. If it is not, reinstall it: opencompanion service install (it needs at least one pairing first).
2. Is the machine awake and online? A sleeping laptop or a dropped network shows the device offline until it wakes and reconnects; it comes back on its own.
3. Is the pairing still there? opencompanion backends should list the app. If it does not, pair again.
4. Can it reach the app? Confirm the app's API base is reachable from this machine (a firewall or VPN can block it).

A CLI shows a re-auth badge

When a connected coding CLI's login has expired, the app badges it as needing re-auth (OpenCompanion detects this on a slow background probe and reports it - it never fixes a CLI's login for you). To clear it, re-login in that CLI on the host machine:

opencompanion connect claude-code    # re-detect and log the CLI back in

Once the CLI is signed in again, the daemon's next probe reports it healthy and the badge clears on reconnect. OpenCompanion never touches your subscription quota to check this, so a badge can lag a fresh login by up to the probe interval; a dispatch attempt re-probes immediately.

Where the logs are

• What ran - the audit log: opencompanion log. This is the record of every dispatched run and policy change.

• Service output (crashes, startup errors):

  OS	Where
  macOS	~/Library/Application Support/opencompanion/logs/opencompanion.log and opencompanion.err.log
  Linux	journalctl --user -u opencompanion
  Windows	Check opencompanion service status; the logon task's run history is in Task Scheduler

An update is stuck or the new version misbehaves

The daemon stages an update but applies it only while idle, so a long-running job legitimately delays it. To see where things stand and act:

opencompanion update --check      # installed vs latest, and whether auto-update is on
opencompanion update              # apply now, on demand
opencompanion update --rollback   # flip back to the previous version and restart

If a release ever misbehaves, --rollback returns you to the version you were on before. To stay put while you investigate, pin with opencompanion update --auto off (see Updating). A staging failure (a bad download or a failed checksum) never touches your running version - the daemon logs it and retries on the next cycle.