agent troubleshooting

log locations

Logs live in two trees. The service and everything it launches write machine-wide under %PROGRAMDATA%\Owlette\logs\; the desktop app writes per-user.

machine-wide — C:\ProgramData\Owlette\logs\

Main shared-logger files use rotating file handlers: 10 MB per file, 5 backups. owlette-host rotates the three files it writes by size, keeping exactly one .1 sibling each: 10 MB for service_stdout.log and service_stderr.log, 2 MB for service_host.log. tmp/status_writer.log rotates at 100 KB with 2 backups, and pairing_debug.log uses plain writes. Old main logs are auto-deleted after 90 days by default.

per-user — %LOCALAPPDATA%\app.owlette.desktop\logs\

This one is per-user: it belongs to whoever the app runs as, typically the machine's auto-login account, not the LocalSystem account the service runs as. It rotates at 4 MB and keeps 4 files (owlette-desktop_<date>.log), and its timestamps are local time, so they line up with service.log — a field report usually wants both.

debug mode

Run the service in debug mode to see real-time console output:

cd C:\ProgramData\Owlette\agent\src
python owlette_service.py debug

common issues

agent won't start

Symptoms: Service fails to start, or starts and immediately stops.

Check:

1. Run in debug mode to see the error:

   cd C:\ProgramData\Owlette\agent\src
   python owlette_service.py debug

2. Check service.log for startup errors, and service_host.log for what owlette-host saw — the spawn, the exit code the agent returned, and any crash-loop backoff. A traceback that never reached the logger lands in service_stderr.log.
3. Verify Python is installed: C:\ProgramData\Owlette\python\python.exe --version.
4. Verify C:\ProgramData\Owlette\config\config.json is valid JSON.

Common causes:

• Corrupt config.json: repair it, or move it aside and re-run pairing so the agent can create a fresh config.
• Missing packaged files or Python dependencies: repair or reinstall the agent.
• Broken service registration after a failed upgrade: rerun the packaged repair flow or reinstall the service.

agent shows offline in dashboard

Symptoms: Machine shows offline (red/grey) despite the service running.

Check:

1. Verify service is running: sc query OwletteService.
2. Check service.log for Firebase connection errors.
3. Verify internet connectivity.
4. Check firewall rules for outbound HTTPS (port 443) to the configured API host (owlette.app or dev.owlette.app) and Firebase services.
5. Verify firebase.site_id in C:\ProgramData\Owlette\config\config.json.

Common causes:

• No internet: The agent keeps running locally but cannot update Firestore.
• OAuth token expired: Check for token refresh errors in service.log; the agent should auto-refresh when the stored refresh token is valid.
• Wrong site_id: The config is paired to a different dashboard site.
• Firebase disabled: Check firebase.enabled is true in config.json.
• Heartbeat has not refreshed yet: Presence and metrics use an adaptive interval: about 5 seconds while the desktop app's window is open, 30 seconds when monitored processes are active, and 120 seconds when idle.

"agent not authenticated" error

Symptoms: Log shows "Agent not authenticated - no refresh token found".

Cause: The agent's stored OAuth tokens are missing or corrupt.

Fix:

1. Delete the token file and re-pair:

   del C:\ProgramData\Owlette\.tokens.enc

2. Run the pairing flow:

   C:\ProgramData\Owlette\python\python.exe C:\ProgramData\Owlette\agent\src\configure_site.py

3. The console prints a 3-word pairing phrase and the authorization link for the server this machine is bound to, then starts polling. Open that link from any device — this machine, a phone, another computer — and enter the phrase. Nothing opens a browser here on its own.
4. Wait for authorization to complete, then restart the service.

If pairing fails before authorization completes, check C:\ProgramData\Owlette\logs\pairing_debug.log.

processes not auto-restarting

Symptoms: Configured processes crash but are not restarted.

Check:

1. Verify launch_mode is always, or scheduled with the current time inside a configured schedule window.
2. Check if the relaunch_attempts limit has been reached. The counter resets on manual restart.
3. Verify the exe_path exists and is correct.
4. Check service.log for launch errors.
5. Check time_delay and time_to_init if restarts are delayed after a failure.

Common causes:

• Executable not found: Launch fails, process_launch_failed is logged, and an exe_missing alert may be sent.
• Relaunch limit reached: The reboot prompt should have appeared.
• Permission error: Service may not have access to the executable path.
• User-session launch issues: Managed launches use CreateProcessAsUser and process_launcher.py; check service/session token errors in service.log.

When the executable is missing, the service logs process_launch_failed and sends an exe_missing alert with suggested sibling paths when it can find likely replacements. The dashboard toast can open the process edit dialog with a suggested path pre-filled.

connectionmanager states

The agent's connection to Firestore follows a state machine. Check service.log for the current state:

Fatal-ish errors are not a permanent terminal state; the connection manager keeps retrying with long backoff while you restore access or re-pair.

If stuck in BACKOFF:

1. Check internet connectivity.
2. Verify Firebase project is accessible.
3. Wait for the automatic retry. Circuit-breaker recovery probes run after about 5 minutes, and repeated failures can stretch retry backoff up to 1 hour.

high cpu/memory usage

Symptoms: The owlette service itself uses excessive resources.

Normal usage: ~20-50 MB RAM, <1% CPU.

If excessive:

1. Check if debug logging is enabled.
2. Look for rapid reconnection loops in service.log.
3. Verify no circular config updates; hash tracking should prevent feedback loops.
4. Check whether the desktop app's window is open. Metrics and heartbeat uploads run about every 5 seconds while it is on screen, 30 seconds while processes are active, and 120 seconds when idle. Closing the window back to the tray drops the machine to the slower cadence.

desktop app won't open

Symptoms: Clicking open owlette from the tray does nothing, or the window closes immediately after opening.

Check:

1. Look at service.log for the launch attempt — the service reports both the launch and a missing executable.
2. Look at %LOCALAPPDATA%\app.owlette.desktop\logs\owlette-desktop.log — the app records its own startup there in release builds, so a crash after launch shows up here rather than in service.log.
3. Verify the desktop app exists: C:\ProgramData\Owlette\app\owlette-desktop.exe.
4. Try launching manually:

   "C:\ProgramData\Owlette\app\owlette-desktop.exe"

5. Confirm the WebView2 runtime is installed — the app renders in it and cannot open a window without it. The installer adds it when missing, but a blocked or offline install can leave it absent:

   (Get-ItemProperty 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}').pv

tray status looks stale

Symptoms: The tray status does not match the service or Firebase state.

Check:

1. Confirm OwletteService is running.
2. Inspect C:\ProgramData\Owlette\tmp\service_status.json.
3. Check C:\ProgramData\Owlette\tmp\status_writer.log for status-file write decisions.

The service writes service_status.json immediately when important state changes and otherwise uses a 30-second refresh floor with content-change throttling. The status file has nested service, firebase, and health sections.

remote install or update fails

Symptoms: A dashboard deployment fails before the installer runs, or an agent self-update does not complete.

Check:

1. Check service.log for the command result.
2. For self-updates, check C:\ProgramData\Owlette\logs\installer_update.log.
3. Check whether C:\ProgramData\Owlette\logs\update_in_progress.json exists after a failed self-update.
4. Verify the installer URL is reachable from the target machine.

Common causes:

• Missing sha256_checksum: install_software refuses to run remote installers without this 64-character SHA-256 checksum.
• Missing checksum_sha256: update_owlette refuses to self-update without this checksum field.
• Missing target_version: The agent can infer a version from the installer filename, but the command should send target_version explicitly.
• No interactive user session: Third-party installers run in the user's desktop session; a user must be logged in.
• Wrong silent flags or verify path: The installer may complete but fail post-install verification.

temperature monitoring driver (pawnio)

The agent reads CPU temperatures through LibreHardwareMonitor, which uses the PawnIO kernel driver — a signed, sandboxed driver that runs vetted modules instead of exposing raw hardware access. The installer deploys PawnIO 2.2.0 automatically and it is Microsoft-signed, HVCI-compatible, and not on any vulnerable-driver blocklist, so no Defender exclusions are needed. (Versions up to 3.1.0 used the WinRing0 driver instead, extracted at runtime as python.sys — upgrading removes that driver, its R0python service, and the Defender exclusions it required.)

Verify the driver: Get-Service PawnIO should show Running (it is demand-start, so Stopped is also normal when nothing is reading sensors). If it is missing, CPU temperatures read as blank while GPU temperatures keep working through vendor APIs — reinstall it with winget install namazso.PawnIO or by re-running the agent installer.

Opt out of temperature monitoring: set "temperature": { "enabled": false } in C:\ProgramData\Owlette\config\config.json — it takes effect within one metrics tick, no restart needed. All sensor reads stop; temperature fields simply disappear from the dashboard. A missing temperature section means enabled.

Note: PawnIO is a shared component (other tools such as FanControl use it too), so uninstalling the agent leaves it installed — remove it separately from installed apps if it is no longer needed.

service management commands

# Check service status
sc query OwletteService

# Start service
net start OwletteService

# Stop service
net stop OwletteService

# Restart service
net stop OwletteService && net start OwletteService

# View service configuration
sc qc OwletteService

All commands require Administrator privileges.

The desktop app restarts the service without one. restart service in the app's menu writes tmp/restart.flag; the service picks it up on its next loop and exits 42, and owlette-host relaunches it immediately — no UAC prompt. The tray icon's right-click menu carries the same item, with one difference: a service that is already stopped has no loop to read the flag, so the tray starts it through the SCM instead, which is the one path that can prompt for elevation.

getting help

• Use submit bug report in the desktop app's menu — it also takes feature requests and general feedback. The agent attaches the machine's system metrics and the last 100 lines of service.log automatically, along with the hostname and site id, so the report arrives diagnosable.
• Email us at support@owlette.app
• File a bug or feature request on GitHub