Claude Code
6cebab9a4a
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>
NxM Agent OS
A personal agentic operating system built on plain markdown files. Tool-agnostic — works with Claude Code, Ollama, or any LLM harness. Based on the framework from the AI Daily Brief episode "How to Build a Personal Agentic Operating System" (Nufar Gaspar, 2026-04-25).
How it works
Every agent interaction reads from and writes back to files in this repo. No databases, no APIs, no vendor lock-in. The files ARE the system.
The seven layers
| Layer | File(s) | Purpose |
|---|---|---|
| Identity | identity.md |
Who the user is, communication style, values, hard limits |
| Context | context/ |
Dated, task-specific working files |
| Brain | brain.md |
Persistent facts — infra, services, IPs, standing decisions |
| Memory | memory/ |
Short and long-term session notes |
| Skills | skills/ |
Repeatable workflows, each self-improving |
| Processes | skills/*/context/handoff.md |
Output passed between chained skills |
| Automation | cron on 172.27.40.3 | Scheduled skill execution |
Quick start for a new LLM
If you are an LLM reading this repo for the first time:
- Read
identity.md— who you're working for, hard limits, communication style - Read
brain.md— all infrastructure facts: IPs, services, ports, agents, standing decisions - Read
memory/active-projects.md— what's currently in flight - Read
memory/constraints.md— things you must never do - Read
CLAUDE.md— project status and architecture details
Do NOT take any action without reading identity.md first. The hard limits there are non-negotiable.
Live agent ecosystem
The NxM infrastructure runs 12+ named agents across Docker containers and VMs. Every agent writes logs to /opt/agent-os/logs/<agent>/last-run.json and most publish web dashboards to agents.nxm.co.za/<agent>/.
Key agents:
- Citadel MCP (port 8300) — central tool server, 37 tools covering Docker, Plane, TRMM, Directus, file ops, web search
- Raven (port 8400) — notification hub (Discord + Gmail), all alerts route through here
- Jon Snow (port 8900) — chief of staff orchestrator with approval gates
- Maester (port 8800) — NIST CSF compliance reporting
- Hermes Native (VM 108) — primary conversational agent with WhatsApp + Honcho memory
- Tarly (port 8750) — backup monitoring (OPNsense configs + Proxmox)
- Vexis (via Hermes, VM 108) — workshop/TRMM scripting agent for client devices
See brain.md for the complete agent table with ports and schedules.
Adding a new skill
- Create
skills/<skill-name>/skill.md— what the skill does and how - Create
skills/<skill-name>/learnings.md— starts empty, fills over time - Create
skills/<skill-name>/eval.json— scoring criteria - Add a cron job on 172.27.40.3 calling the skill
- The infra-monitor watchdog will automatically pick it up
Runtime
- Server:
/opt/agent-os/on 172.27.40.3 (Ubuntu, Docker host) - Repo:
git.nxm.co.za/admin/agent-os(SSH:gitea-local:admin/agent-os.git) - LLM inference: Ollama at
http://172.27.40.20:11434(local) or Anthropic API (Claude Code/Hermes) - Scheduled jobs: cron on 172.27.40.3
- Agent web pages:
/opt/sites/<name>/→ agents.nxm.co.za
Infra reference
Cross-repo links to supporting documentation:
Credential policy
All API keys and passwords live in ~/.nxm-keys (chmod 600). Never write credential values into code, config files, logs, or documentation. Reference the file location instead.