chore(repo): initialize team collaboration repository

2026-07-27 20:40:12 +08:00
commit c91a64fddb
109 changed files with 21121 additions and 0 deletions
@@ -0,0 +1,56 @@
+# 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.