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>
74 lines
3.8 KiB
Markdown
74 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
1. **Read `identity.md`** — who you're working for, hard limits, communication style
|
|
2. **Read `brain.md`** — all infrastructure facts: IPs, services, ports, agents, standing decisions
|
|
3. **Read `memory/active-projects.md`** — what's currently in flight
|
|
4. **Read `memory/constraints.md`** — things you must never do
|
|
5. **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
|
|
|
|
1. Create `skills/<skill-name>/skill.md` — what the skill does and how
|
|
2. Create `skills/<skill-name>/learnings.md` — starts empty, fills over time
|
|
3. Create `skills/<skill-name>/eval.json` — scoring criteria
|
|
4. Add a cron job on 172.27.40.3 calling the skill
|
|
5. 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:
|
|
- [IP & Port Map](https://git.nxm.co.za/admin/nxm-infrastructure/src/branch/main/Quick%20Reference/IP%20%26%20Port%20Map.md)
|
|
- [Docker Stacks](https://git.nxm.co.za/admin/nxm-infrastructure/src/branch/main/Quick%20Reference/Docker%20Stacks.md)
|
|
- [Network Overview](https://git.nxm.co.za/admin/nxm-infrastructure/src/branch/main/Infrastructure/Network%20Overview.md)
|
|
|
|
## 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.
|