v0.1.0 · MIT License

Aura OS Technical Documentation

1. Executive Overview

Aura OS treats the local filesystem as an agent's workspace and extended memory. Instead of relying solely on linear prompt history, Aura OS enables agents to reason, persist, and extend capabilities freely through structured files, custom tools, and automated environment hooks.

2. Decoupled Architecture & System Features

Core operating system abstractions and subagent runtime primitives.

To isolate agent operations from user application code, Aura OS implements a Decoupled Environment Layout. All event logs, subagent state databases, and custom tools are sandboxed inside a hidden .aura-workspace/ directory, leaving the primary user workspace clean.

# Decoupled Workspace File Hierarchy

my_project/                 <-- User Workspace
├── .gitignore              <-- Auto-ignores hidden .aura-workspace/
├── src/                    <-- Application code
└── .aura-workspace/        <-- Hidden Isolated Environment
    ├── config/config.yml   <-- Runtime settings
    ├── state/
    │   ├── sessions/       <-- Primary session SQLite event DBs
    │   └── subagents/      <-- Sandboxed subagent instances (<id>/state.db)
    ├── tools/              <-- Dynamic custom tool manifests
    └── skills/             <-- Workflow playbooks (SKILL.md)

🤖 Isolated Subagent Runtime subagents/<id>

Primary agents spawn child subagents for dedicated tasks (e.g. data processing, code auditing). Each subagent operates in its own sandboxed SQLite environment (state/subagents/<id>/state.db), eliminating memory cross-contamination.

📬 Asynchronous Mailbox Bus state/bus/

Subagents communicate asynchronously across instances through a file-backed Mailbox Bus. Messages and event triggers pass between subagents without prompt context leakage.

📚 Skill Playbooks skills/SKILL.md

Modular workflow instructions loaded on-demand. Skills contain Markdown playbooks and executable scripts that guide agents through domain-specific workflows.

💾 SQLite Event Persistence default.db

All agent actions, tool calls, and environmental events are indexed in an SQLite database. When context saturates, historic turns are compacted into structured summary nodes.

3. Use-Cases

Run pre-packaged agent use-case scenarios directly in your workspace.

3.1 Stanford Smallville 25-Agent Town Simulation Social Simulation

View Full Interactive Report ↗

Replication of the Stanford Smallville benchmark. Tests isolated subagent database memory streams (state/subagents/<id>/state.db) and zero-prompt-leakage town host clock signals.

▶ How to Run 25-Agent Simulation (CLI Command)

# Run Command:

cd use-cases/smallville-town && python3 run_real_25_town.py

3.2 AutoKaggle ML Competition Pipeline ML Pipeline

View Full Interactive Report ↗

AutoKaggle use-case package for automated machine learning engineering with LightGBM model sweeps, hypothesis feature engineering, and dry-run submission guards.

▶ How to Bootstrap & Run AutoKaggle Pipeline (CLI Commands)

# Run Commands:

aura new ~/kaggle/playground-s5e1

python use-cases/auto-kaggle/scripts/bootstrap.py --workspace ~/kaggle/playground-s5e1 --slug playground-s5e1 --mode offline

3.3 Autonomous Ralph Verification Loop

The Ralph Loop provides test-driven autonomous goal execution. The agent iterates through code modifications, re-runs verification commands, and exits when tests pass.

aura kernel ralph . --goal "Fix failing daemon unit tests" --verify "npm test" --max-steps 5

4. Quick Start & CLI Instructions

# 1. Recommended One-Click Setup Script

curl -fsSL "https://raw.githubusercontent.com/zc6600/aura/main/bin/setup.sh?t=$(date +%s)" | bash

# 2. Local CLI Commands

aura new my_agent_project

aura agent --goal "Create a web scraper"

aura config llm.model claude-3-5-sonnet

5. Cloudflare Deployment

Deploy this documentation portal directly to Cloudflare Pages:

# Direct Wrangler Deployment

npx wrangler pages deploy website --project-name=aura-os-website