# Check agent health

Diagnose an agent that will not connect, or prove a fresh install is sound before you run anything.

The doctor command runs a read-only posture check against an agent install. It changes nothing, so it is safe to run on a production host at any time. Run it as the user the agent runs as, with the same environment, so it checks the identity and the endpoint the agent really uses:

```bash
export AMFELT_API_ENDPOINT=<your-endpoint>
amfelt doctor
```

Doctor checks the endpoint in `AMFELT_API_ENDPOINT`, else the one in the agent's config file, else the one the agent remembered at registration. With none of these, as on a host that has not registered yet, it skips the reachability check rather than failing it, and can still exit with `0`. Set the variable whenever you want proof that the install can reach a specific endpoint.

## What it checks

- **Identity**: the agent's key and its organization and agent identifiers are present and loadable, under `$AMFELT_DIR` or `~/.amfelt` when that is unset.
- **Key storage**: which tier the install uses to hold its key, and whether that tier's posture contract is met. On a filesystem-backed install that includes the file permissions.
- **Reachability**: the Amfelt platform answers at the configured endpoint.
- **Posture**: the platform's view of this agent. Today this check is skipped for an agent's own credentials; see the agent's posture in the app instead.

## Reading the exit code

| Code | Meaning |
| --- | --- |
| `0` | Pass or warn. The install is operational. |
| `1` | At least one check failed. Remediate before running syncs. |
| `2` | Doctor could not build its configuration. Check the environment variables and the config path. |

An exit code of `2` is a different problem from `1`: nothing was checked at all, because the command could not work out what to check.

## Before registration

Run the subset of checks that do not need an identity when you want to prove a fresh install can reach the platform, before you spend an invite code on it. With `AMFELT_API_ENDPOINT` exported as above:

```bash
amfelt doctor --include-unregistered
```

## In automation

Emit the report as JSON when a script or a pipeline needs to read it rather than a person:

```bash
amfelt doctor --json
```

This is the check worth running at the end of an automated agent rollout, gating on the exit code.

## Reading the agents list

The app tells you a complementary half of the story:

- An agent that registered but never connected is waiting for `amfelt channel` to run, or waiting for approval.
- An agent that stopped heartbeating has lost its outbound connection: the process died, the host went away, or the network to the platform broke.
- An agent that is connected but whose runs fail is a source, credential, or configuration problem rather than an agent problem.

## Next

Review how the agent was set up in [Register an agent](/docs/guides/cli/register-an-agent/), or go looking at what its runs did in [Follow a run](/docs/guides/monitoring/follow-a-run/).