Project Structure

Every Nexus OS project follows a standard directory layout.

Directory Layout

my-project/
├── nexus.config.yaml    # Main configuration file
├── data/
│   └── nexus.db         # SQLite database (auto-created)
├── agents/
│   ├── researcher.wasm  # Compiled agent modules
│   └── analyzer.wasm
├── skills/
│   ├── summarize.wasm   # Skill handlers
│   └── translate.wasm
└── logs/                # Optional log directory
    └── audit.log

Files

nexus.config.yaml

The main configuration file. Contains all settings for agents, supervisors, cost budgets, trust requirements, and more. See Configuration Reference.

data/nexus.db

SQLite database that stores:

Agent records and state
Supervisor configurations
Saga/workflow executions
Cost tracking data
Audit log entries
AXIS trust cache

Auto-created on first run. Do not delete while agents are running.

agents/

Directory for compiled agent WASM modules. Agents are compiled from your source code and placed here.

skills/

Directory for broker skill handlers. WASM modules that handle specific task patterns.

Creating a Project

bash

naos init my-project

# Output:
# ✓ Created project structure
# ✓ Generated nexus.config.yaml
# ✓ Initialized SQLite database
# ✓ Created example agent

Project Detection

Nexus OS looks for nexus.config.yaml in the current directory and parent directories. You can run naos commands from any subdirectory of your project.

Updating

nexus.config.yaml