dtoro/oikos
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

plan: client bootstrap fetches CLIENTS.md as primary orientation

Browse Source 
CLIENTS.md is the entry point for a machine joining the homelab.
AGENTS.md is the AI agent persona layer on top. Both fetched, but
CLIENTS.md comes first.
This commit is contained in:
authentik Default Admin
2026-07-07 23:59:22 +02:00
parent 79dc87d584
commit 8653f3036d
1 changed files with 5 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
plans/2026-07-07-client-lifecycle-in-go.md
View File

@@ -45,7 +45,7 @@ secrets, state, and lifecycle transitions.
│ WORKSTATION (bare machine) │ │ WORKSTATION (bare machine) │
│ │ │ │
│ 1. curl bootstrap.sh | sudo bash (from raw Gitea URL) │ │ 1. curl bootstrap.sh | sudo bash (from raw Gitea URL) │
│ → fetches AGENTS.md, OIKOS.md, tools/ to /opt/homelab/ │ │ → fetches CLIENTS.md, AGENTS.md, OIKOS.md, tools/ │
│ → calls POST /api/v1/clients/enroll │ │ → calls POST /api/v1/clients/enroll │
│ → receives age keypair + Infisical identity │ │ → receives age keypair + Infisical identity │
│ → writes /etc/age/key.txt, /etc/infisical/identity │ │ → writes /etc/age/key.txt, /etc/infisical/identity │
@@ -94,7 +94,7 @@ unnecessary — the only things a workstation actually needs on disk are:
| Artifact | Why local? | How delivered | | Artifact | Why local? | How delivered |
|----------|-----------|---------------| |----------|-----------|---------------|
| `AGENTS.md` + `OIKOS.md` | Agent reads these at startup; can't query MCP before knowing MCP exists | Fetched once by bootstrap.sh, cached to `/opt/homelab/` | | `CLIENTS.md` + `AGENTS.md` + `OIKOS.md` | Agent reads these at startup; can't query MCP before knowing MCP exists | Fetched once by bootstrap.sh, cached to `/opt/homelab/` |
| `.sops.yaml` | Recipient rules for age decryption (DR fallback if Infisical is down) | Served by `GET /api/v1/clients/{slug}/context` | | `.sops.yaml` | Recipient rules for age decryption (DR fallback if Infisical is down) | Served by `GET /api/v1/clients/{slug}/context` |
| SOPS-encrypted secrets | DR cold recovery (Infisical is primary) | Served by `GET /api/v1/secrets/sops-backups` or fetched on enrollment | | SOPS-encrypted secrets | DR cold recovery (Infisical is primary) | Served by `GET /api/v1/secrets/sops-backups` or fetched on enrollment |
| Age private key | Decrypt SOPS files | Delivered once in enroll response, written to `/etc/age/key.txt` | | Age private key | Decrypt SOPS files | Delivered once in enroll response, written to `/etc/age/key.txt` |
@@ -115,7 +115,7 @@ GET /api/v1/clients/{slug}/context?since=2026-07-07T12:00:00Z
Returns a JSON delta: Returns a JSON delta:
```json ```json
{ {
"agent_files_changed": ["AGENTS.md", "OIKOS.md"], "agent_files_changed": ["CLIENTS.md", "AGENTS.md", "OIKOS.md"],
"sops_config_changed": true, "sops_config_changed": true,
"tools_changed": ["setup-caveman.sh"], "tools_changed": ["setup-caveman.sh"],
"since": "2026-07-07T12:05:00Z" "since": "2026-07-07T12:05:00Z"
@@ -140,7 +140,8 @@ git clone "$REPO_HTTPS" "$CLONE_DIR"
# New: fetch only what the agent needs # New: fetch only what the agent needs
mkdir -p /opt/homelab/.agents/shared /opt/homelab/.agents/skills mkdir -p /opt/homelab/.agents/shared /opt/homelab/.agents/skills
curl -s "$RAW_URL/AGENTS.md" -o /opt/homelab/AGENTS.md curl -s "$RAW_URL/CLIENTS.md" -o /opt/homelab/CLIENTS.md
curl -s "$RAW_URL/AGENTS.md" -o /opt/homelab/AGENTS.md
curl -s "$RAW_URL/.agents/OIKOS.md" -o /opt/homelab/OIKOS.md curl -s "$RAW_URL/.agents/OIKOS.md" -o /opt/homelab/OIKOS.md
curl -s "$RAW_URL/.agents/shared/caveman.md" -o /opt/homelab/caveman.md curl -s "$RAW_URL/.agents/shared/caveman.md" -o /opt/homelab/caveman.md