# AKOS — Infrastructure inventory (Phase 0, read-only reconnaissance, 2026-11-01)

All facts below were observed with commands run from the operator laptop; nothing was changed.

## Target name and ingress

| Item | Observed | Command |
|---|---|---|
| DNS `akos.spboucher.ai` | `A 51.161.112.61` (resolver local and 1.1.1.1) | `dig +short akos.spboucher.ai` |
| 51.161.112.61 | **BHS64**, OVH Beauharnois, Ubuntu 24.04, public gateway of the MacLustr Tunnel | CLAUDE.md + `ssh BHS64` |
| Tunnel provider | **Not Cloudflare.** WireGuard hub `wg0` 10.67.0.1 on BHS64 (udp 51820, udp 443 redirected) + **Caddy** TLS auto (`/etc/caddy/Caddyfile`, `import sites/*.caddy`), routes managed by `/usr/local/bin/tunnelctl` | `ssh BHS64 sudo cat /etc/caddy/Caddyfile` |
| Caddy global | `protocols h1 h2`, `trusted_proxies static private_ranges`, error pages `/etc/caddy/errors` | same |
| Existing routes | 36 routes, none for `akos.spboucher.ai` | `mld tunnel status` |
| WireGuard peers | 17 Macs connected (handshakes < 2 min) | `mld tunnel status` |
| Route creation | `mld deploy <app>` with `tunnel.domain` in the manifest runs `tunnelctl add <domain> <node>:<port>` on BHS64 (additive; `mld tunnel rm` reverses it) | mld README |

## Orchestration

| Item | Observed |
|---|---|
| Gateway node | **M1M32** (`~/maclustr-dispatch`, manifests `~/dispatch/apps/*.json`, registry `~/dispatch/registry.json`) |
| Deploy path | `mld stage` (new app) or `mld fetch --from <node>` → `mld deploy <app> [--node X]` → PM2 processes, local healthcheck `http://127.0.0.1:<port><health_path>`, Caddy route, public healthcheck → registry; `mld adopt` makes the deployed dir a git clone (origin spbgit) |
| Process manager | PM2 (`pm2 startup` done by `mld prepare`); `mld heal` every 5 min on M1M32 restarts missing PM2/launchd/wg1/routes |
| Git hosting | spbgit bare repos `M1M32:~/srv/git/<name>.git`, alias `gitsrv` on all nodes and laptop |
| Claude Code (laptop) | `2.1.316`, MCP servers in `~/.claude.json` (apify, tavily, worldbank, openalex, anthropic, polymarket, etherscan, notion, hfmarketdata); `~/.claude/settings.json` has a PreToolUse auto-approve hook — **must not be overwritten** |
| `claude mcp add --transport http <name> <url> --header "Authorization: Bearer …" -s user` | supported (verified with `claude mcp add --help`) |

## Candidate nodes (mld scan 2026-11-01)

| Node | CPU/RAM | Free RAM | Disk | PM2 apps | Postgres | pgvector | Python | Node | wg1 | sandbox-exec |
|---|---|---|---|---|---|---|---|---|---|---|
| **M4M64c** | M4 Max 16c / 64 GB | 54.7 GB | 318 GB free | 5 procs (chat-spboucher-ai ×3, note-web, note-worker) | 17.11 Homebrew, `listen_addresses='localhost'`, pg_hba trust on local/127.0.0.1/::1 | available (`vector`) | 3.13.18 (brew), uv 0.13.6, 3.12 via uv | v26.10.0, pnpm 12.6.0 | 10.67.0.33 | `/usr/bin/sandbox-exec` present; profile `(deny network-outbound)(allow … localhost)` **blocks** `curl https://example.com` (exit 6) and **allows** `curl http://127.0.0.1:8480` (200) — verified |
| M2M32c | M2 12c / 32 GB | 22 GB | 417 GB free | 0 | 17.11, pgvector available | yes | 3.13.15 | v26.8.2 | 10.67.0.20 | present |
| M3U96b | M3 Ultra 32c / 96 GB | 77 GB | 394 GB | 8 procs | 17.11 | ? | 3.14 | v25 | 10.67.0.11 | present |

Decision: **pin M4M64c** (same reasoning as note-spboucher-ai: Postgres 17 + pgvector already initialised, large RAM, few apps, wg1 connected, sandbox-exec verified). M2M32c is the fallback (`mld move akos --to M2M32c`).

## Ports (M4M64c, `lsof -iTCP -sTCP:LISTEN`)

Listening: 5432 (Postgres, loopback), 3283 (ARD), 8480 (note), 8500 (chat). Free and chosen for AKOS: **8520** (HTTP app: UI + `/api/v1` + `/mcp` + `/docs`), **8521** (egress proxy, loopback only).

## Secret store

- No central vault (Vault/1Password CLI) found on the nodes. **macOS login keychain** (`/usr/bin/security`) is available on every node and is used by AKOS: items `service=akos`, `account=<secret-name>`; AKOS stores only `vault://keychain/akos/<name>` references.
- App secrets (`SESSION_SECRET`, bootstrap admin password, DB URL) live in `~/apps/akos/.env` (mode 600) on the node; copy in `~/Desktop/Cluster/secrets/akos/` on the laptop (outside git).

## Backups

- Existing convention on M4M64c: `~/backups/<app>/` + remote copy on `M3U96b:~/backups/<app>/` (note-spboucher-ai does this nightly). AKOS follows it: `scripts/backup.sh` (pg_dump + artifacts) → `~/backups/akos/` → rsync `M3U96b:~/backups/akos/`.

## Unknowns / not inspected

- OVH/BHS64 firewall (ufw) details beyond what Caddy exposes (80/443) — not needed for an additive route.
- GoDaddy zone contents other than the `akos` record (not queried; only the A record was verified).
- Whether `pgvector` embeddings will be used: AKOS v1 uses PostgreSQL full-text search + trigram (`pg_trgm`) for retrieval; no external embedding model is called. Recorded as a limitation, not as "semantic" vectors.

## Rollback plan

1. `mld tunnel rm akos` (removes the Caddy route on BHS64; DNS untouched).
2. `pm2 delete akos-web akos-worker akos-proxy` on M4M64c (or `mld retire akos`).
3. `dropdb akos` on M4M64c (after `scripts/backup.sh` if data must be kept).
4. Remove `~/apps/akos`, the manifest `M1M32:~/dispatch/apps/akos.json`, keychain items `security delete-generic-password -s akos`.
5. Laptop: `claude mcp remove akos -s user` (only the `akos` entry is ever added; nothing else in `~/.claude.json` or `settings.json` is touched by the installer).

## Addendum (post-deployment, 2026-11-01 15:10)
- Route live: `akos.spboucher.ai → 10.67.0.33:8520 (M4M64c)` in BHS64 Caddy (added by `mld deploy`); certificate Let's Encrypt valid until 2027-01-30.
- Laptop → M4M64c direct SSH (Tailscale 100.125.225.117) timed out during the build while the node was healthy on the LAN; a jump alias `akosnode` (ProxyJump M1M32 → 192.168.2.103) was added to the laptop `~/.ssh/config`. Not a cluster change.
- Registry: `mld status` lists `akos M4M64c 8520 akos.spboucher.ai online`; `~/apps/akos` adopted as git repo (origin spbgit `akos.git`).