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

# Health Checks

> How the Velatir desktop client monitors itself, and how to read velatir health

## Overview

`velatir health` reports whether the desktop client can do its job: the host is running, desktop config is syncing, the last update did not fail, and the browser extension can receive its configuration.

Read it with [`velatir health`](/desktop-app/cli#health). Exit code is `0` when every check is healthy and non-zero when any check fails, so it works as a monitoring probe.

## States

| State      | Meaning                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Ok`       | Agent reachable; host up; config sync succeeding (or still inside the first-boot grace); last update not failed; no known browser-delivery fault. |
| `Degraded` | At least one of those checks failed.                                                                                                              |

## Reading `velatir health`

```bash theme={null}
velatir health
```

```text theme={null}
Health:    Degraded

Checks:
  [ ok ] host-running
  [FAIL] config-sync
         reason: host has not reported a config sync (hosted services may not have started)
  [ ok ] last-update
```

Add `--json` for the raw snapshot.

## Checks

| Check                    | Fails when                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `host-running`           | No `Velatir` host process.                                                                |
| `config-sync`            | Last poll failed, or the host has been up more than two minutes without reporting a sync. |
| `last-update`            | Last update outcome is `Failed` or `RolledBack`.                                          |
| `native-messaging`       | Browser policy blocks the Velatir native-messaging host (omitted if not probed).          |
| `managed-storage`        | Force-installed extension has no ingest token (omitted if not probed).                    |
| `cli-native-messaging`   | On-disk macOS CLI does not advertise native-messaging support (omitted off macOS).        |
| `force-install-coverage` | A managed browser is missing the Velatir force-install entry (omitted if not probed).     |

## If it shows a problem

* **Host not running / no config sync:** the host process may be crash-looping. Run `velatir logs --host` and share the output with support.
* **Browser-delivery checks:** see [Troubleshooting](/desktop-app/troubleshooting).
* **Anything else:** `velatir status` plus `velatir logs --host -f`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="life-buoy" href="/desktop-app/troubleshooting">
    Resolve a degraded state.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/desktop-app/cli">
    The `health` and `test` commands in detail.
  </Card>
</CardGroup>