NEXUS OS
A bootable AI operating environment — a ReAct-style agent orchestrator with skill auto-discovery, a permission model, and a FastAPI server, shipped as a Linux distribution rather than an app.
Problem
Agent frameworks generally assume they are a library inside someone else's application. That leaves the interesting parts — what the agent is allowed to touch, how new capabilities get registered, what happens on reboot — as the host application's problem. NEXUS OS inverts that: the agent runtime is the system, the machine boots into it, and skills and permissions are first-class parts of the environment rather than configuration passed in at call time.
Approach
- ›A ReAct-style orchestrator drives the observe → think → act loop, with each action routed through a permission gate before execution
- ›Skills are auto-discovered from disk: drop a module into the skills directory and its schema and documentation are registered without editing the orchestrator
- ›A FastAPI server exposes chat, skill listing, job control, and health endpoints, so the environment is drivable over HTTP as well as locally
- ›Capability modules extend the base loop with vision, retrieval-augmented generation, scheduling, and homelab monitoring
- ›The whole stack is packaged as a bootable Linux distribution so the environment is reproducible on bare metal or a VM
Architecture
# NEXUS OS
┌──────────────────────────────────────────────────┐
│ Bootable Linux Distribution │
│ │
│ base image ──► services ──► agent runtime │
└────────────────────────┬─────────────────────────┘
│
▼
┌──────────────────────────────────────────────────┐
│ FastAPI Server │
│ │
│ /chat /skills /jobs /health │
└────────────────────────┬─────────────────────────┘
│
▼
┌──────────────────────────────────────────────────┐
│ ReAct Agent Orchestrator │
│ │
│ observe ──► think ──► act ──► observe ... │
│ │ │
│ ▼ │
│ permission model gate │
│ (each skill call checked before run) │
└───────────┬──────────────────────┬───────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Skill Registry │ │ Capability Modules │
│ │ │ │
│ auto-discovery │ │ vision · RAG │
│ from skills/ dir │ │ scheduler │
│ schema + docs │ │ homelab monitoring │
└───────────────────┘ └──────────────────────┘
Tech Stack
FastAPI
Server & agent API
Python
Orchestrator & skills
Linux
Bootable base image
systemd
Service supervision
RAG stack
Retrieval over local corpora
Local LLM
Inference backend
Challenges
Permissions without paralysis
A gate on every action is only useful if it is granular enough to say yes safely. Skills declare what they touch, so the model can be scoped per capability rather than as a single all-or-nothing switch.
Auto-discovery vs. predictability
Loading arbitrary modules from disk is convenient and fragile in equal measure. Skills are validated against a schema at registration, so a malformed one fails loudly at boot rather than mid-loop.
Packaging a live system
Turning a running stack into a bootable image means pinning the model runtime, service ordering, and GPU drivers together — the pieces most likely to drift independently.