agent

Two pieces ship to every machine. The service does the supervising — it is what this section is mostly about, and it runs whether or not anyone is signed in. The desktop app is how you see and change what that service is doing while standing at the machine; it is the window below, and it is covered in configuration and the system tray.

what the agent does

how it runs

The agent runs as a Windows service hosted by owlette-host.exe, a small Rust supervisor that ships in tools\ and replaced NSSM in 3.0.0. It registers the service to start automatically on boot, relaunches the agent if it crashes (5 seconds, backing off to 60 seconds once five crashes land inside a five-minute window), and honours the agent's own exit codes: 42 (restart flag) and 43 (self-restart watchdog) relaunch immediately, while a clean exit 0 stops the service.

tools\owlette-host.exe (Service Host)
  └── python\python.exe agent\src\owlette_runner.py (Bridge)
        └── owlette_service.py (Main Service Loop)
              ├── firebase_client.py (Cloud Sync)
              │     ├── auth_manager.py (OAuth Tokens)
              │     ├── firestore_rest_client.py (REST API)
              │     └── connection_manager.py (State Machine)
              ├── command_router.py (Command Dispatch)
              │     ├── sync_commands.py (roost — sync_pull, cancel_sync, rollback_to_version)
              │     │     └── sync_downloader.py, sync_assembler.py, sync_state.py
              │     ├── machine_commands.py (Public-API Commands — capture_screenshot)
              │     └── process_commands.py (Process Control — restart_process)
              ├── sync_scrub.py (roost Integrity Scrub + Orphan-Chunk Reap — hourly check)
              ├── config_sync.py (Config Reconciliation — local, cloud, cached remote)
              ├── shared_utils.py (Config, Logging, Metrics)
              │     └── temp_sensors.py (CPU/GPU Temperature via PawnIO)
              ├── health_probe.py (Startup Health Checks)
              ├── installer_utils.py (Remote Deployment)
              ├── registry_utils.py (Software Inventory)
              └── mcp_tools.py (Remote Command Execution)

Spawned into user session by the service:
  ├── app\owlette-desktop.exe (Desktop App — tray icon, configuration window, reboot prompt)
  ├── owlette_cortex.py (Local AI Agent)
  │     ├── cortex_firestore.py (Message Polling & Response Writing)
  │     ├── cortex_tools.py (MCP Tool Server for Agent SDK)
  │     └── mcp_tools.py (Tool Implementations)
  ├── process_launcher.py (Application Launcher)
  └── session_exec.py (User Session Command Executor)

Launched on demand:
  └── configure_site.py (Device Code Pairing, and the desktop app's back end
        for join / leave site, bug reports and reboot control)

See hoot tools reference for the current tool list.

service lifecycle

startup

1. Initialize logging (RotatingFileHandler, 10 MB per file, 5 backups)
2. Upgrade config schema if needed (automatic migration)
3. Run the startup health probe and publish it to service_status.json, so the tray can surface a problem before any cloud call happens
4. Construct the Firebase client (soft-fail: cloud disabled, no site, or no refresh token each leave the machine in local-only mode)
5. Acquire the console user token, then launch the desktop app (tray icon) — deliberately ahead of the cloud work, so the operator sees the service starting immediately
6. Classify the previous session's end (see below), queueing a warning event that is sent once Firebase connects
7. Start the Firebase client: sync config with Firestore, then connect
8. Recover running processes (adopt PIDs from previous session)
9. Enter the main loop, which launches hoot on its first pass (if enabled)

session state classification

On every startup the agent reads C:\ProgramData\Owlette\tmp\session_state.json (written continuously by the previous run — alongside app_states.json and reboot_state.json) and uses the "alive heartbeat" and any recorded shutdown intent to categorise how the last session ended:

The classifier depends only on shared_utils and stdlib — no Firebase, no logging config — so it is safe to import from any agent context (main loop, metrics thread, signal handler, user-space dialogs). Source: agent/src/session_state.py.

main loop (every 5 seconds)

1. Check all configured processes — detect crashes, stalls, exits
2. Auto-restart crashed processes when launch mode is active
3. Firestore commands are processed by the Firebase command listener; the 5-second service loop handles process monitoring, hoot IPC, Firebase enable/disable checks, and periodic maintenance
4. Ensure hoot is running (if enabled)
5. Process hoot IPC commands (Tier 2 tool calls)
6. Check for Firebase state changes (enable/disable)

shutdown

Every operator-initiated stop — console control handler or SCM stop watcher — funnels through one shared path, and whichever trigger arrives first does the work:

1. Record the stop locally as a clean external stop, before anything that can touch the network — this local record is what keeps the next startup classifier from reporting unexpected_reboot
2. Cap the remaining Firestore request timeouts at 3 seconds, so a stalled call cannot eat the whole shutdown window
3. Log the agent_stopped event
4. Stop the Firebase client — this is the write that marks the machine offline, and it stops the background threads afterwards (offline first, or the write has no transport left)
5. Write the final status file saying the service is down

The desktop app is deliberately left running — its footer is where the operator finds start service to bring the agent back.

Source: agent/src/owlette_service.py → graceful_shutdown(), reached from agent/src/owlette_runner.py's signal handler or the SCM stop watcher.

key directories