---
title: "Project Structure"
description: "Every Nexus OS project follows a standard directory layout. The main configuration file. Contains all settings for agents, supervisors, cost budgets, trust requirements, and more. See Configuration Reference. SQLite data"
resource: https://www.aiagents.nexus/docs/manual/configuration/project-structure
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# 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](/docs/manual/configuration/nexus-config-yaml).

### 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.