> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turen.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Solutions for frequently encountered problems

## Agent Won't Start

**Symptom:** `turen-watchdog run` exits immediately or shows an error.

**Check the basics:**

```bash theme={null}
# Is the daemon already running?
turen-watchdog status

# Check if the LaunchDaemon is loaded
sudo launchctl list | grep turen
```

**Common causes:**

* The agent is already running as a LaunchDaemon. Stop it first before running manually.
* Missing registration key on first run. Set `TUREN_REGISTRATION_KEY` environment variable.
* Network connectivity: the agent needs to reach `api.prod.turen.io` over HTTPS.

## Proxy Not Responding

**Symptom:** `curl http://127.0.0.1:7778/health` fails or Claude Code can't connect.

**Check the proxy:**

```bash theme={null}
# Is the proxy process running?
ps aux | grep turen-proxy

# Is port 7778 in use?
lsof -i :7778
```

**Common causes:**

* The agent isn't running. Start it with `sudo launchctl load /Library/LaunchDaemons/dev.turen.watchdog.plist`.
* Port 7778 is in use by another process. Check with `lsof` and stop the conflicting process, or configure a different port.
* The proxy crashed. Check logs with `log show --predicate 'subsystem == "dev.turen.watchdog"' --last 5m`.

## Claude Code Not Using the Proxy

**Symptom:** Claude Code works but sessions don't appear in the dashboard.

**Check your environment:**

```bash theme={null}
echo $ANTHROPIC_BASE_URL
```

This should output `http://127.0.0.1:7778`. If it's empty or points elsewhere, the Turen installer may not have configured Claude Code correctly. Try reinstalling from the DMG, or contact support.

## Registration Failed

**Symptom:** `turen-watchdog run` shows a registration error.

**Common causes:**

* **Invalid registration key**: The key may have already been used (they're single-use) or revoked. Generate a new one in the dashboard.
* **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:

```bash theme={null}
sudo launchctl unload /Library/LaunchDaemons/dev.turen.watchdog.plist
sudo launchctl load /Library/LaunchDaemons/dev.turen.watchdog.plist
```

## 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:**

* Verify the proxy is being used (`echo $ANTHROPIC_BASE_URL` should show `http://127.0.0.1:7778`)
* Check that the agent is running and registered
* Look at agent logs for upload errors

## Need More Help?

If your issue isn't covered here, contact us at [support@turen.io](mailto:support@turen.io) with:

* Your macOS version
* The output of `turen-watchdog status`
* Relevant log output