Everything you need to build with AitherOS

The Complete Guide

131 services. 15 agents. 110 cmdlets. 273 scripts.
One guide to rule them all.

131

Services

15

Agents

110

Cmdlets

273

Scripts

SCROLL TO START

Get Started

Quick Start

From zero to running in 5 steps. Works on Windows, macOS, and Linux. Total time: ~10 minutes first run, ~30 seconds after.

Prerequisites

⏱ ~5 min

Make sure you have these installed before starting.

Docker Desktop

winget install Docker.DockerDesktop

Required — all services run in containers

PowerShell 7+

winget install Microsoft.PowerShell

Cross-platform automation engine

Ollama

winget install Ollama.Ollama

Local LLM inference server

Tips

Docker must have Docker Compose v2 enabled
WSL2 backend recommended on Windows
At least 16GB RAM, 24GB+ recommended for larger models

Step 1 of 5

Docker Profiles

Start only what you need. Each profile brings up a logical group of services.

--profile core7

Gateway, Mind, Pulse, Node

--profile intelligence15

Reasoning, Intent, Judge, STaR

--profile memory8

FastMem, Strata, Spirit, Chronicle

--profile perception11

Feed, Scraper, OCR, Neurons

--profile agents18

All specialist agents

--profile social7

LinkedIn, Discord, RSS, Email

--profile security9

Secrets, Vault, DLP, RBAC

--profile training6

Harvest, Trainer, Evolution

--profile gpu7

vLLM, Embedding, TTS, STT

--profile mcp4

MCP servers — GitHub, FS, Browser

--profile all131

Everything — full stack

Core Concepts

Cognitive Architecture

A six-pillar cognitive cycle modeled after biological cognition. Context is the central hub. Learning closes the loop. Every decision is traceable.

LOOP

P1

Intent

PARSE

Every cognitive cycle begins here.

16 intent types10-level effort scale<50ms classification

P2

Reasoning

THINK

Deep thinking — only when complexity demands it.

SASE 4-phase tracesCriticality gatingSTaR training capture

P3

Orchestration

ACT

Coordinate tools, agents, and LLMs.

15 specialist agents6 model tiersMCP tool protocol

P4

Context

REMEMBER

The central hub — ALL state flows through Context.

5 memory layers~1ms L0 accessParallel tier queries

P5

Creation

MAKE

Generate artifacts — code, images, media, narratives.

4 creative domainsIntent-to-codeQuality gating

P6

Learning

EVOLVE

Closes the loop — the system improves itself.

Outcome captureBrier score calibrationJSONL training export

Service Reference

131 Services

Explore all 131 microservices across 19 groups. Search by name, port, or description. Every service is a FastAPI app with health checks and lifecycle management.

Sort:

18 groups·118 services shown·Ports 3000-8790

Developer Reference

API Reference

Interactive API explorer for core services. Every endpoint with methods, parameters, and cURL examples. Hit /docs on any service for auto-generated Swagger UI.

Genesis

Service bootloader — lifecycle management for all 131 services

Base URL:http://localhost:8001

💡 Every AitherOS service exposes /health and /docs (Swagger UI) endpoints. Hit http://localhost:PORT/docs for auto-generated API docs.

Internal Plurality

Specialist Agents

15 agents with persistent memory, distinct personas, and specialized capabilities. Not prompt wrappers — each is a FastAPI service with its own port, state, and lifecycle.

✨:8773

Aither

The Intelligence

Core orchestrator — routes to specialist agents, maintains inner life & affect

Multi-agent routingAffect stateInner monologuePain monitoring

Open agent

⚡:8140

Demiurge

The Divine Craftsman

Intent-to-code engine — takes ideas, ships projects

Full project scaffoldingCode generationTest writingPR creation

Open agent

📖:8770

Saga

The Epic Storyteller

Narrative, roleplay, world-building with character persistence

Character memoryScene generationWorld stateMulti-voice

Open agent

📚:8779

Lyra

The Research Librarian

Deep research — scouts, neurons, source verification

Scout dispatchNeuron networkSource rankingCitation chains

Open agent

🏛️:8778

Atlas

The Infrastructure Titan

Roadmap management, blast radius analysis, dependency mapping

Roadmap trackingBlast radiusRisk analysisSprint planning

Open agent

📰:8781

Vera

The Herald

Interactive articles, tutorials, documentation generation

Article generationTutorial scaffoldsMarkdown exportSEO optimization

Open agent

🎮:8190

Prometheus

The Worldsmith

Tick-based simulation engine for emergent behavior testing

Tick simulationEntity managementRule engineTimeline replay

Open agent

📡:8782

Hera

The Broadcaster

Content distribution & scheduling across platforms

Cross-platform postSchedulingAnalyticsA/B testing

Open agent

🎬:8774

Director

The Creative Director

Creative direction & media production orchestration

Media orchestrationStyle directionAsset managementQuality control

Open agent

Agent Hierarchy

AitherAgent — orchestrator (routes all queries)

├── InfraAgent, ServicesManager — infrastructure

├── GenesisAgent — monitoring & lifecycle

├── Demiurge, Saga, Lyra, Director — specialist tier

├── Vera, Hera, Atlas — content & planning

└── Prometheus, Forge — experimental tier

Automation Layer

AitherZero

110 cmdlets, 273 automation scripts across 13 domains. PowerShell 7+ module that manages the entire ecosystem.

Bootstrap

pwsh -File ./bootstrap.ps1 -Mode New -InstallProfile Minimal -NonInteractive

Run tests

pwsh -File ./AitherZero/library/automation-scripts/80-testing/0402_Run-UnitTests.ps1

Validate syntax

pwsh -File ./AitherZero/library/automation-scripts/90-maintenance/0906_Validate-Syntax.ps1 -All

Build module

pwsh -File ./AitherZero/build.ps1

Environment

0000–0099

Setup, bootstrapping, prerequisites

Get-SystemInfoInitialize-EnvironmentTest-Prerequisites

Infrastructure

0100–0199

Hyper-V, certificates, networking

New-CertificateSet-NetworkPolicyInitialize-HyperV

Dev Tools

0200–0299

Git, Node, Docker, VS Code setup

Install-DevToolsSet-GitConfigInstall-VSCodeExtensions

Build

2000–2099

Image building, module compilation

Build-GenesisImageBuild-ServiceImagesPush-Images

Lifecycle

4000–4099

Start, stop, restart services

Start-GenesisStop-GenesisRestart-Service

Testing

0400–0499

Pester, pytest, PSScriptAnalyzer

Run-UnitTestsRun-PSScriptAnalyzerRun-IntegrationTests

Reporting

0500–0599

Test reports, dashboards, metrics

Generate-TestReportGet-CoverageReport

Git & AI

0700–0799

GitHub integration, automation

Sync-RepositoryCreate-PullRequest

Maintenance

9000–9999

Reset, cleanup, health checks

Reset-EnvironmentInvoke-DeepCleanValidate-Syntax

When Things Break

Troubleshooting

Interactive diagnostic guide for common issues. Each problem comes with causes, fixes, and copy-paste commands. Because things break — and that's okay.

Filter:

Quick Diagnostic

docker ps --filter "name=aither" -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Run this first — shows all AitherOS containers with their status and port mappings.

Deep Dives

Documentation Resources

Comprehensive guides, architecture docs, and reference material. Organized by topic for quick access.

Architecture

Architecture Overview

System architecture & design decisions

docs/ARCHITECTURE.md

Service Dependency Map

Service relationships & boot order

docs/SERVICE_DEPENDENCY_MAP.md

Coding Standards

Patterns, anti-patterns, templates

docs/CODING_STANDARDS.md

Service Endpoints

All service ports & endpoints

docs/SERVICE_ENDPOINTS_REFERENCE.md

Guides

Quick Start

Get running in 3 steps

QUICKSTART.md

Docker Profiles

Service profiles & composition

docs/DOCKER_PROFILES.md

Secrets Service

Secret management & vault

docs/SECRETS_SERVICE.md

STaR Implementation

Self-Taught Reasoner training

docs/STAR_IMPLEMENTATION.md

Integration

Integration Testing Guide

All 131 services tested

docs/INTEGRATION_TESTING_MASTER_GUIDE.md

Context Integration

Memory & context pipeline

docs/CONTEXT_INTEGRATION_SUMMARY.md

Unified Streaming

SSE streaming architecture

docs/UNIFIED_STREAMING_SYSTEM.md

MCP Setup

Model Context Protocol server config

.github/COPILOT-MCP-SETUP.md

Operations

Troubleshooting

Common issues & fixes

docs/troubleshooting/

Security Fixes

Security audit & remediation

docs/SECURITY_FIXES_SUMMARY.md

Technical Debt

Debt tracking & remediation plan

docs/TECHNICAL_DEBT_ANALYSIS.md

Docker Build Optimization

Build speed improvements

docs/DOCKER_BUILD_OPTIMIZATION.md

External Resources

GitHub Architecture Demo Investor Pitch

The Complete Guide

Quick Start

Prerequisites

Tips

Docker Profiles

Cognitive Architecture

Intent

Reasoning

Orchestration

Context

Creation

Learning

131 Services

Cognition

Agents

Infrastructure

Perception

Security

Social

Memory

GPU

Core

Training

Automation

Communication

MCP

Orchestration

Creative

Mesh

Bootloader

UI

API Reference

Genesis

Specialist Agents

Aither

Demiurge

Saga

Lyra

Atlas

Vera

Prometheus

Hera

Director

Agent Hierarchy

AitherZero

Environment

Infrastructure

Dev Tools

Build

Lifecycle

Testing

Reporting

Git & AI

Maintenance

Troubleshooting

Container keeps restarting

Service not responding on expected port

LLM calls timing out or returning errors

PowerShell module not loading / cmdlet not found

Python import errors in service

Docker build fails

Agent doesn't remember previous conversations

Request blocked by security middleware

Documentation Resources

Architecture

Guides

Integration

Operations

External Resources