Check Agent Health

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:

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  

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:

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:

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 , or go looking at what its runs did in Follow a Run .