Architecture Overview

Nexus OS is structured in layers, each providing a distinct capability. Understanding the architecture helps you make better decisions about how to use each feature.

Layer Diagram

┌─────────────────────────────────────────────┐
│                CLI / Dashboard               │
│  naos create │ naos status │ naos dashboard  │
├─────────────────────────────────────────────┤
│              Broker Routing                  │
│  Skill Match → WASM → LLM Fallback          │
├─────────────────────────────────────────────┤
│           Orchestration Primitives           │
│  Supervisor │ Saga │ Workflow │ Pool         │
├─────────────────────────────────────────────┤
│            Trust & Cost Layer                │
│  AXIS Verification │ Budget Enforcement      │
├─────────────────────────────────────────────┤
│             Execution Layer                  │
│  WASM Sandbox │ Agent Runtime │ Audit Log    │
├─────────────────────────────────────────────┤
│               Storage Layer                  │
│  SQLite (local) │ Durable Objects (edge)     │
└─────────────────────────────────────────────┘

Components

CLI (naos)

The command-line interface is the primary way to interact with Nexus OS. Every operation — creating agents, running sagas, checking costs — goes through naos.

Dashboard

A web-based UI served by the naos binary itself. No separate server needed. Provides real-time monitoring of all components.

Broker

The routing engine that decides how to handle incoming tasks. It checks skills first (cheapest), then WASM modules, then falls back to LLM (most expensive).

Orchestration Primitives

Four patterns for coordinating agents:

• Supervisor — Monitor and restart failed agents
• Saga — Multi-step transactions with rollback
• Workflow — Sequential pipelines with data passing
• Pool — Parallel execution with result merging

Trust Layer (AXIS)

Integration with AXIS Trust for agent verification. Checks T-Scores, Trust Tiers, and Credit Ratings before allowing agents to run.

Cost Controller

Per-agent budget enforcement. Tracks spending, enforces limits, and can pause, throttle, or alert when budgets are exceeded.

Execution Layer

Agents run in WASM sandboxes with no ambient authority. Every action is logged to the audit trail.

Storage

Local SQLite database for development and testing. Cloudflare Durable Objects for edge deployment.

Data Flow

User Request
     │
     ▼
┌─────────┐    ┌──────────┐    ┌───────────┐
│  Broker  │───▶│  Trust   │───▶│   Cost    │
│ Routing  │    │  Check   │    │  Check    │
└─────────┘    └──────────┘    └───────────┘
                                     │
                                     ▼
                              ┌───────────┐
                              │  Execute  │
                              │  (WASM)   │
                              └───────────┘
                                     │
                                     ▼
                              ┌───────────┐
                              │  Audit    │
                              │   Log     │
                              └───────────┘

Design Principles

1. Single binary — Everything ships in one executable
2. Zero dependencies — No Docker, no Kubernetes, no cloud services required
3. Erlang-inspired — Supervision trees, let-it-crash philosophy
4. Cost-aware — Every operation has a cost, every agent has a budget
5. Trust-first — Verify before you trust, always