# FlashOps Host Agent

The Host Agent is a pull-mode process that runs on a test host. The first
implemented slice supports:

- read-only host fingerprint discovery;
- enrollment into a Test Host record;
- one-time bearer token issuance;
- local credential persistence with mode `0600`;
- authenticated heartbeats and Host status updates;
- server-side heartbeat aging to `DEGRADED` after 15s and `OFFLINE` after 30s;
- optional gateway Basic Auth for deployments that enable an authenticated proxy.

Step leases, command templates, event uploads, artifacts, and completion
reporting remain the next slice.

## Local run

Start the control plane in one terminal:

```bash
make dev
```

Register and send one heartbeat in another:

```bash
make dev-agent
```

Run continuously:

```bash
make dev-agent-loop
```

By default the Agent state is stored at `~/.flashops/agent-state.json`. It
contains the raw bearer token and is created with mode `0600`. The control
plane stores only its SHA-256 digest.

## Configuration

| Variable | Purpose |
|---|---|
| `FLASHOPS_AGENT_SERVER` | Control plane base URL |
| `FLASHOPS_AGENT_HOST_ID` | Bind to an existing Test Host ID |
| `FLASHOPS_AGENT_HOST_NAME` | Bind to or create a Test Host by name |
| `FLASHOPS_AGENT_STATE_PATH` | Local credential state path |
| `FLASHOPS_AGENT_ENROLLMENT_TOKEN` | First-registration secret |
| `FLASHOPS_AGENT_BASIC_USER` | Optional authenticated-proxy user |
| `FLASHOPS_AGENT_BASIC_PASSWORD` | Optional authenticated-proxy password |

Production registration is denied when the control plane does not have
`FLASHOPS_AGENT_ENROLLMENT_TOKEN` configured. Store that value in
`/etc/flashops/flashops.env` with root-only permissions; never put it in the
systemd unit or repository.