admin/agent-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive update — bring all Agent OS docs current for LLM onboarding

Browse Source 
All files were 5-7 weeks stale. Updated brain.md (complete service/agent/VPN/cron
inventory), identity.md (current expertise + infra context), CLAUDE.md (full agent
ecosystem table, Citadel tool registry, gotchas), README.md (LLM quick-start guide),
all memory files (current projects, decisions, constraints, persistent facts), and
infra-monitor skill.md (current container list with criticality tiers).

Also fixed: git remote switched from HTTP+embedded-token to SSH, removed references
to decommissioned services (Netbird, WireGuard, Flowise, Zabbix), corrected Ollama
IP (172.27.40.20), TrueNAS IP (172.27.40.220), and added 20+ services/agents that
were built since the last commit.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Code
2026-06-19 17:15:11 +00:00
parent 638b2edd56
commit 6cebab9a4a
9 changed files with 427 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
brain.md
+99 -36
View File
@@ -1,64 +1,127 @@
# Brain
Core facts read by all skills. Keep under 1000 words. Update when infrastructure changes.
Last updated: 2026-04-30
Core facts read by all skills. Keep under 1500 words. Update when infrastructure changes.
Last updated: 2026-06-19
---
## Infrastructure
**Primary server:** 172.27.40.3 — Ubuntu Server LTS, Docker host
**Kubuntu desktop:** 172.27.6.139 — NxM-AI, runs Ollama
**TrueNAS NAS:** 172.27.40.220 (Servers40), management: 172.27.6.221
**Firewall:** OPNsense at 172.27.6.1
**Primary server:** 172.27.40.3 — Ubuntu Server LTS, Docker host, all agent runtimes
**Ollama inference host:** 172.27.40.20 — Windows 11 Pro (NxM-AI), Vulkan GPU, Scheduled Task auto-start
**TrueNAS NAS:** 172.27.40.220 (data) / 172.27.6.221 (mgmt) — 35.6 TB, NFS shares for ISOs + Proxmox backups
**Firewall:** OPNsense at 172.27.6.1 (mgmt UI, not routed gateway)
**Proxmox VE:** 172.27.40.2 — PVE 9.1.1, 2× Xeon Gold 6138 (80 vCPUs), 252 GB RAM
**Hermes Native VM:** 172.27.40.30 (VM 108) — dedicated agent VM, Honcho memory, WhatsApp connected
**Tactical RMM:** 172.27.40.4 (VM 101) — remote management for all Nexum clients
**Home Assistant:** 172.27.10.6 (VM 100) — IoT automation
**Synology DS423+:** 172.27.40.80 — Coetzee off-site backup NAS, Active Backup via S2S
**VLANs:**
| VLAN | Name | Subnet |
|---|---|---|
| 40 | Servers40 | 172.27.40.0/24 |
| 20 | Workshop20 | 172.27.20.0/24 |
| 10 | IoT10 | 172.27.10.0/24 |
| VLAN | Name | Subnet | Gateway |
|---|---|---|---|
| 40 | Servers40 | 172.27.40.0/24 | 172.27.40.1 |
| 20 | Workshop20 | 172.27.20.0/24 | 172.27.20.1 |
| 10 | IoT10 | 172.27.10.0/24 | 172.27.10.1 |
## Key Services (172.27.40.3)
| Service | Port | URL |
| Service | Port | URL | Role |
|---|---|---|---|
| Portainer | 9443 | https://172.27.40.3:9443 | Docker management |
| Nginx Proxy Manager | 80/81/443 | http://172.27.40.3:81 | Reverse proxy, SSL termination |
| Uptime Kuma | 3002 | kuma.nxm.co.za | HTTP monitoring |
| Gitea | 3000 | git.nxm.co.za | Self-hosted git, all docs + code |
| Headscale | 8080 | headscale.nxm.co.za | VPN (self-hosted Tailscale) |
| Vaultwarden | 8222 | vault.nxm.co.za | Password manager |
| Open WebUI | 3010 | chat.nxm.co.za | Chat UI for Ollama + MCP |
| Plane | 8095 | plane.nxm.co.za | Project/task tracking |
| Homarr | 7575 | http://172.27.40.3:7575 | Dashboard |
| Grafana | 3020 | grafana.nxm.co.za | Monitoring dashboards |
| InfluxDB | 8086 | internal | Time-series DB for monitoring |
| NetBox | 8100 | netbox.nxm.co.za | IPAM, network documentation |
| NocoDB | 8150 | rvd.nxm.co.za | RvDM birthday DB (personal, NOT Nexum) |
| InvenTree | 8160 | inventree.nxm.co.za | IT stock + BOM tracking (testing) |
| Directus | 8850 | directus.nxm.co.za | Nexum client CRM |
| Nextcloud | — | — | Phone backup |
| Wetty | 8450/8451 | terminal.nxm.co.za / term.nxm.co.za | Web SSH terminal |
| RustDesk | 21115-21119 | internal | Self-hosted remote desktop relay |
| SearXNG | 8600 | internal | Search backend for sam + citadel |
| iVentoy | 26000 | internal | PXE boot server |
## AI / Agent Stack
**LLM inference:**
- **Ollama** on 172.27.40.20:11434 — models: gemma4, llama3.1:8b, phi4
- **Claude Code** on 172.27.40.3 — primary AI assistant (Anthropic API)
- **Hermes Native** on 172.27.40.30 — OpenRouter, Honcho memory, WhatsApp
- **Hermes Cloud** on 172.27.40.3:8643 — claude-sonnet-4-6, Citadel MCP wired
**Named agents (all Docker on 172.27.40.3 unless noted):**
| Agent | Port | Role | Schedule |
|---|---|---|---|
| hodor-gateway | 8200 | Simple Ollama gateway (POST /ask) | On-demand |
| citadel-mcp | 8300 | MCP SSE+HTTP server, 37 tools | Always-on |
| raven-notify | 8400 | Discord + Gmail notifications | Always-on |
| sam-research | 8500 | SearXNG + Ollama research | On-demand |
| qyburn-coder | 8700 | LLM coding agent (approve/reject) | On-demand |
| maester-reports | 8800 | NIST CSF compliance reports | On-demand |
| jon-snow | 8900 | Chief of staff orchestrator | Always-on |
| bran-changelog | — | Git changelog generator | Daily 06:00 |
| varys-monitor | — | Service HTTP reachability checks | Cron every 15 min |
| tarly-backup | 8750 | OPNsense config + Proxmox backup monitor | Daily 04:00 SAST |
| hermes-cloud | 8643 | Claude-powered conversational agent | Always-on |
| hermes-native | VM 108 | Primary Hermes agent (WhatsApp) | Always-on |
| vexis (workshop) | VM 108 | Nexum workshop agent (TRMM scripts) | On-demand via Hermes |
**Citadel MCP tools (37):** file ops, Docker management, Plane issues/projects/pages, TRMM (agents/scripts/confirm), Directus CRM, Proxmox backups, Qyburn task/approve, Sam research, web search, propose_file_change.
## Cron Jobs (172.27.40.3)
| Schedule | Job | Log |
|---|---|---|
| Portainer | 9443 | https://172.27.40.3:9443 |
| Nginx Proxy Manager | 80/81/443 | http://172.27.40.3:81 |
| Uptime Kuma | 3002 | http://172.27.40.3:3002 |
| Gitea | 3000 | https://git.nxm.co.za |
| Headscale | 8080 | https://headscale.nxm.co.za |
| Netbird | 3479/udp | https://netbird.nxm.co.za |
| Vaultwarden | 8222 | https://vault.nxm.co.za |
| Flowise | 3010 | http://172.27.40.3:3010 |
| Plane | 8095 | https://plane.nxm.co.za |
| Zabbix | 8091 | https://zabbix.nxm.co.za |
| Homarr | 7575 | http://172.27.40.3:7575 |
| Daily 06:00 | bran-changelog/run.sh | logs/bran.log |
| Daily 06:00 | zenarmor-pull.py | monitoring/logs/zenarmor-pull.log |
| Daily 02:05 | tarly hub-backup.sh | logs/tarly-backup/hub-backup.log |
| Every 1 min | ovpn-status.py | logs/ovpn-status.log |
| Every 30 min | trmm-frappe-sync.py | logs/trmm-frappe-sync.log |
## AI Stack
## OpenVPN S2S Sites
- **Ollama** on 172.27.6.139:11434 (bound to 0.0.0.0)
- **Models:** gemma4, qwen2.5-coder:7b
- **Flowise** on 172.27.40.3:3010 — visual agent/flow builder
- **Claude Code** — primary AI assistant, runs on Kubuntu
| Site | Tunnel IP | Status | Notes |
|---|---|---|---|
| bezhuis | 172.16.17.2 | COMPLETE | NAT + DNS overrides, LAN access live |
| mwp | 172.16.17.3 | COMPLETE | Monitoring live |
| coetzee | 172.16.17.4 | COMPLETE | Monitoring-only + Active Backup to Synology |
| fwlaw | — | PENDING | Awaiting migration |
## Agent OS Runtime
- Files: `/opt/agent-os/` on 172.27.40.3
- Local edit path: `/home/nxm/Documents/agent-os/` on 172.27.6.139
- Repo: `https://git.nxm.co.za/admin/agent-os`
- Repo: `git.nxm.co.za/admin/agent-os` (SSH remote: `gitea-local:admin/agent-os.git`)
- Scheduled jobs: cron on 172.27.40.3
- LLM calls: `http://172.27.6.139:11434`
- LLM calls: `http://172.27.40.20:11434` (Ollama) or Anthropic API (Claude Code / Hermes)
- Agent web pages: `/opt/sites/<name>/` served at agents.nxm.co.za
## Key Paths on Server
- Docker stacks: `/opt/stacks/`
- Agent OS: `/opt/agent-os/`
- Agent web pages: `/opt/sites/`
- Credentials: `~/.nxm-keys` (chmod 600) — NEVER write values elsewhere
- SSH keys: `~/.ssh/` (ED25519)
- NxM infrastructure docs: `/home/nxm/Documents/NxM Linux Server/`
- Nexum project docs: `/home/nxm/Documents/Nexum Projects/`
## Standing Decisions
- TrueNAS will move to a dedicated server — avoid hardcoding 172.27.40.5 in automation
- NPM handles all SSL termination — internal services use HTTP, NPM adds HTTPS
- NFS preferred for Linux-to-Linux file sharing
- Docker Compose only (no Kubernetes)
- All destructive actions require explicit confirmation before execution
- NPM handles all SSL termination — internal services use HTTP
- Docker Compose only (no Kubernetes, no Swarm)
- All destructive actions require explicit confirmation
- Credentials only in `~/.nxm-keys` — never in output, logs, or config files
- Netbird fully removed (2026-05-28) — VPN is Headscale + OpenVPN S2S
- WireGuard fully removed (2026-05-30) — replaced by OpenVPN S2S
- Open WebUI → Citadel MCP: auth_type must be `none` (empty bearer = silent failure)
- Docker → OPNsense API: run from host, never from inside a container (HTTP 400)
- NocoDB = RvDM personal only — never use for Nexum projects
- Nexum client data layer = Directus CRM