Skip to main content

​
Agent Won’t Start

Symptom: turen-watchdog run exits immediately or shows an error. Check the basics:
Common causes:
  • The agent is already running as a LaunchDaemon. Stop it first before running manually.
  • Network connectivity: the agent needs to reach api.prod.turen.io over HTTPS.
A missing registration key does not stop the agent from starting. The daemon runs fine without a key: it just stays unregistered until you sign into the desktop app (which registers it over local IPC) or supply a key on a headless install.

​
Claude Code Sessions Not Recorded

Symptom: Claude Code works but sessions don’t appear in the dashboard. Turen records sessions from Claude Code’s local transcripts via hooks it registers in managed-settings.json. If sessions aren’t showing up:
  • Confirm the agent is running and registered with turen-watchdog status.
  • Confirm Turen’s hooks are present in Claude Code’s managed settings. If not, the installer may not have configured Claude Code correctly: try reinstalling, or contact support.
  • Check agent logs for upload errors: log show --predicate 'subsystem == "dev.turen.watchdog"' --last 5m.

​
Registration Failed

Symptom: turen-watchdog run shows a registration error. Common causes:
  • Invalid registration key: The key may have reached its maximum registration count, expired, or been revoked. Check the key in the dashboard or generate a new one.
  • Network error: The agent can’t reach api.prod.turen.io. Check your network and any proxy/firewall settings.
  • Already registered: If the machine was previously registered, it doesn’t need a registration key. Remove the old state file to re-register: rm -rf ~/Library/Application\ Support/Turen/state.json

​
Agent Shows as Inactive in Dashboard

Symptom: The agent appears in the dashboard but shows as “Inactive”. The agent checks in every 5 minutes by default. If it misses several check-ins, it’s marked inactive. Common causes:
  • The machine is asleep or powered off
  • The agent process was stopped
  • Network connectivity issues between the machine and api.prod.turen.io
Restart the agent and it will check in immediately:

​
Sessions Not Appearing in Replay

Symptom: You’ve used Claude Code but sessions don’t show up in the dashboard. Sessions are uploaded periodically, not in real time. Wait a few minutes after your session ends. If sessions still don’t appear:
  • Check that the agent is running and registered
  • Look at agent logs for upload errors

​
Desktop App Won’t Launch (Linux)

Symptom: Running turen-desktop prints a message about running as your normal user or needing a graphical session, or (on older builds) crashes with a GTK error like cannot open display :0. The Turen desktop app is a graphical application. It must run as your normal (non-root) user inside a graphical desktop session, not from a root shell, an SSH session, or a headless server.
  • Don’t run it with sudo or as root. The managed agent (the turen-watchdog service) already runs with the privileges it needs. The desktop app talks to that service over local IPC and only needs to run as you. Launch it as your normal user: turen-desktop, or open Turen from your applications menu.
  • Make sure you’re in a graphical session. If you’re connected over SSH or on a headless machine, there’s no display to render into. Sign in at the physical console (or a remote desktop session) and launch the app there.
  • Headless / server machines don’t need the desktop app. Register the machine with a registration key instead. See Registering a Linux Machine Without a Key below, or install agent-only with TUREN_NO_DESKTOP=1.

​
Desktop App Missing WebKitGTK (Linux)

Symptom: The desktop app fails to start and the installer warned that WebKitGTK was not found, or you see a runtime error about a missing libwebkit2gtk-4.1 library. The Turen desktop GUI renders its interface with WebKitGTK 4.1, which must be installed on the system. Install it with your package manager:
The .deb and .rpm packages declare this dependency automatically. You only need to install it by hand if you used the one-line install.sh script or the raw tarball. After installing it, launch the app again with turen-desktop.

​
Registering a Linux Machine Without a Key (Linux)

Symptom: You installed the agent without setting TUREN_REGISTRATION_KEY and the machine isn’t showing up as registered in the dashboard. If you installed the desktop app (the default for install.sh), you don’t need a registration key. Launch the Turen desktop app as your normal user and sign in or create an account. The app registers the machine over local IPC, with no key or environment file editing required:
For headless, fleet, or CI installs (or when you ran the installer with TUREN_NO_DESKTOP=1), register with a key instead. Generate a registration key in the dashboard, then add it to the agent environment and restart the service:

​
“Binary Not in Allowed List” After Updating turen-pkg

Symptom: After running turen-pkg update (or otherwise replacing the CLI binary by hand), package commands or IPC calls fail with an error like binary not in allowed list. The watchdog verifies the hash of each Turen binary that connects to it. The desktop app, watchdog, CLI (turen-pkg), and Batou scanner are all updated together as one signed bundle so their hashes stay in sync. Updating a single component on its own changes that binary’s hash, so the watchdog no longer recognizes it. Don’t run turen-pkg update as a standalone command. Let the agent auto-update the whole bundle, or reinstall the matching version so every component lines up again:

​
Need More Help?

If your issue isn’t covered here, contact us at support@turen.io with:
  • Your operating system and version
  • The output of turen-watchdog status
  • Relevant log output