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

# NSP Axon Daemon: Core Capabilities and Running Modes

> Learn what axon-daemon does, how it watches processes, serves the state API on port 7842, streams WebSocket events, and executes actions.

The NSP axon daemon (`axon-daemon.exe`) is the runtime substrate that makes everything else in NSP possible. It runs continuously in the background, attaches to live applications, extracts their semantic state, and serves that state — plus the ability to trigger actions — as a typed JSON API on `localhost:7842`. Every SDK call, every agent query, and every action execution flows through this daemon.

## What the Daemon Does

<CardGroup cols={2}>
  <Card title="Watches Processes" icon="eye">
    Scans all running OS processes on a configurable interval and detects supported applications by runtime classification.
  </Card>

  <Card title="Probes Runtimes" icon="magnifying-glass">
    Attaches to each detected app's runtime (V8, CLR, JVM) to extract live semantic state as typed `SubstrateState` objects.
  </Card>

  <Card title="Caches State" icon="database">
    Maintains an in-memory cache of the latest `SubstrateState` for every tracked process, refreshed on the configured poll interval.
  </Card>

  <Card title="Serves the API" icon="server">
    Exposes the full NSP Agent API over HTTP on `localhost:7842` — state reads, app listings, action execution, and WebSocket streams.
  </Card>

  <Card title="Streams WebSocket" icon="bolt">
    Pushes real-time state change notifications to connected WebSocket clients the moment a tracked app's state changes.
  </Card>

  <Card title="Executes Actions" icon="play">
    Dispatches typed actions into target applications, waits for post-action state to settle, and returns updated state in the same response.
  </Card>
</CardGroup>

## Running Modes

The daemon supports two running modes: as a persistent Windows Service (the recommended production setup) and as a foreground process for development and debugging.

<Tabs>
  <Tab title="Windows Service (Recommended)">
    After installation, the daemon runs automatically as the `NSPDaemon` Windows Service. It starts on boot, runs without a logged-in user session, and restarts automatically on failure.

    ```powershell theme={null}
    # Check the current status
    Get-Service -Name NSPDaemon

    # Start the service
    Start-Service -Name NSPDaemon

    # Stop the service
    Stop-Service -Name NSPDaemon

    # Restart the service
    Restart-Service -Name NSPDaemon
    ```

    See [Windows Service](/daemon/windows-service) for full service lifecycle documentation.
  </Tab>

  <Tab title="Foreground Mode (Development)">
    Run the daemon in your terminal for interactive log output, hot-reloading a custom config, or debugging probe issues.

    ```powershell theme={null}
    # Run with default config
    axon-daemon.exe run

    # Run with a specific config file
    axon-daemon.exe run --config path\to\axon.toml

    # Run with debug logging
    axon-daemon.exe run --log-level debug
    ```

    Press `Ctrl+C` to stop. The binary is identical to the one the service uses — `run` is just a different startup mode.
  </Tab>
</Tabs>

## CLI Reference

Every `axon-daemon.exe` command you need is listed below.

| Command     | Description                                             |
| ----------- | ------------------------------------------------------- |
| `run`       | Start the daemon in foreground mode                     |
| `install`   | Register as a Windows Service                           |
| `uninstall` | Remove the Windows Service registration                 |
| `start`     | Start the installed Windows Service                     |
| `stop`      | Stop the running Windows Service                        |
| `keygen`    | Generate a new API key and add it to the keys file      |
| `status`    | Show daemon status and currently tracked processes      |
| `init`      | Write a default `axon.toml` to `C:\ProgramData\Nelieo\` |
| `help`      | Print help for any command                              |

Pass `--help` after any command to see its flags:

```powershell theme={null}
axon-daemon.exe run --help
```

## Health Check Endpoint

Once the daemon is running, call `/health` to confirm it is up and inspect its current state:

```bash theme={null}
curl http://localhost:7842/health
```

The daemon responds with a JSON object:

```json theme={null}
{
  "status": "ok",
  "version": "1.0.0",
  "uptime_secs": 3600,
  "tracked_processes": 3,
  "auth_enabled": true
}
```

<Note>
  If `auth_enabled` is `false`, the daemon is accepting all requests without key validation. This is safe for local development but must never be used in production. See [Authentication](/daemon/authentication).
</Note>

## Log Output

By default, the daemon writes structured JSON logs to stdout (and to the Windows Event Log when running as a service):

```json theme={null}
{"timestamp":"2026-07-20T13:00:00Z","level":"INFO","target":"axon_daemon::engine","message":"NSP Daemon engine starting","version":"1.0.0","port":7842,"auth":true}
{"timestamp":"2026-07-20T13:00:01Z","level":"INFO","target":"axon_watcher::lifecycle","message":"New V8 app detected","app_id":"gmail-12847","pid":12847,"confidence":0.97}
{"timestamp":"2026-07-20T13:00:03Z","level":"INFO","target":"axon_v8","message":"V8 probe complete: 23 SSF objects in 51ms","app_id":"gmail-12847"}
```

Switch to human-readable text format during development by adding this to your `axon.toml`:

```toml theme={null}
[logging]
format = "text"
level = "debug"
```

<Tip>
  Set `level = "debug"` the first time you probe a new application. Debug logs include per-probe timing, confidence scores, and the full list of SSF objects discovered — essential context when building a new agent.
</Tip>