AethOS

Governed agentic operating system for orchestration, evidence, mutations, engineering intelligence, and multi-channel runtime operations.

AethOS separates orchestration from execution through policy, evidence, verification, approval, and audit.

Install · Architecture · Mission Control · Contribute · Docs

What is AethOS?

AethOS is a secure operational intelligence platform — not a chatbot wrapper and not an unrestricted shell.

It routes every operational action through a governed lifecycle:

Channels → Orchestration → Policy → Provider Runtime → Evidence → Verification → Mission Control → Audit

Why it matters: multi-channel intents (chat, Telegram, Mission Control) converge on one orchestration brain with readonly-first analysis, explicit approval for mutations, and auditable artifacts.

Why trust it: no hidden automation · no auto-merge · no silent background coding · evidence before action.

Install AethOS

Operational orchestration runtime for governed AI systems.

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/pilotmain/AethOS/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/pilotmain/AethOS/main/install.ps1 | iex

Windows with curl.exe:

curl.exe -fsSL https://raw.githubusercontent.com/pilotmain/AethOS/main/install.ps1 | powershell.exe -NoProfile -ExecutionPolicy Bypass -Command -

The install finishes with an interactive setup wizard (it works inside the one-line curl flow): pick your AI provider — Anthropic, OpenRouter, OpenAI, Gemini, Mistral, Groq, xAI, DeepSeek, Together, or a local Ollama/LM Studio server — and your key is validated live and written to .env, along with self-host mode, a generated vault key, and an optional login passphrase. When it ends, the first run is ready to use. Re-run it any time with ./install.sh --onboard; already-installed machines get an update / reinstall / onboard menu, plus --update, --reinstall, and --uninstall.

The installer is idempotent and checkpoints every stage. If a network, dependency, or verification step stops, fix the reported cause and continue:

./install.sh --resume                 # macOS / Linux

.\install.ps1 -Resume                 # Windows

Every stage has focused help (./install.sh --help-step preflight or .\install.ps1 -HelpStep preflight) and a status view (--status / -Status). See the complete installation guide for prerequisites, custom paths, API-only installs, recovery, and upgrades.

Or install from a local clone:

git clone https://github.com/pilotmain/AethOS.git
cd AethOS
./install.sh

The installer will:

Preserve a local checkout or clone into ~/aethos (override with AETHOS_INSTALL_DIR)
Checkpoint preflight, source, backend, frontend, and verification stages
Install the Mission Control API runtime (FastAPI · port 8010)
Configure the local orchestration environment (.env from template)
Install cloud adapters and secure local-vault support
Set up the Mission Control web UI (Next.js · port 3000)
Leave mutation execution disabled by default — enable explicitly in .env
Verify the API, CLI, and frontend toolchain before reporting success
Print the first-run URL, doctor command, recovery command, and log path

Then launch:

./run.sh

On Windows use .\run.ps1. Both launchers support --help / -Help and API-only or web-only modes.

Open the first-run URL below. You'll sign in (if a login passphrase is set), then a short first-run setup learns your name, working hours, timezone, and preferred tone so AethOS can address you naturally.

Surface	URL
First-run / Mission Control UI	http://localhost:3000
Mission Control API	http://127.0.0.1:8010
Health	http://127.0.0.1:8010/api/v1/health

Architecture

AethOS uses a model-as-brain pattern: the Mission Control provider (Anthropic, OpenRouter, local LLM, etc.) routes and answers; AethOS exposes tools, executes governed operations, and enforces policy. Capabilities are provider-agnostic — generic over the MC provider registry and per-tenant credential vault, not hardcoded to any single cloud.

        Channels (Web · Telegram · API)
                    │
                    ▼
         Single-loop orchestration
    (model tool loop · readonly-first routing)
                    │
                    ▼
         Policy + Governance Layer
      (approval · blast radius · blocks)
                    │
                    ▼
     Provider runtime (registry + vault)
    Railway · GitHub · Vercel · AWS · …
                    │
                    ▼
      Evidence + Verification Engine
   (browser capture · artifacts · tests)
                    │
                    ▼
              Mission Control
        (observability · audit · engineering)

Reads run directly. Mutations route through preflight → human approval → the correct provider tool.

Verified capabilities

These are the capabilities verified by pytest tests -q -k beta_smoke and advertised in onboarding:

One model-driven chat loop with governed mutation gates — questions never become deploy targets
Summarize URLs and follow up from conversation memory without canned help blurbs
Render structured operational views to the live Canvas panel
Send Telegram messages with real transport errors surfaced (no generic failure literals)
Diagnose channel health (Telegram webhook, tokens) before workspace or repo commands
Run Railway read-only deployment and inventory checks directly — no preflight job
List provider inventory with live health tables across every connected cloud
Analyze connected GitHub repositories via API — no local workspace registration required
Run multi-model arbiter consensus when at least two models are configured
Check deploy readiness directly; route deploy mutations through approval with the right provider tool
Review connected repo structure, dependencies, and CI workflows via GitHub API

Multi-tenant isolation and mutation governance apply to every capability above.

Mission Control

Mission Control is the operational surface — designed for orchestration clarity, not chat aesthetics.

Sidebar navigation: Runtime · Providers · Browser · Engineering · System
Provider cards with collapsed credential management
Mutation audit trail and operation preflights
Engineering workspace cards, architecture maps, dependency health

Open after ./run.sh: http://localhost:3000/mission-control

Governance guarantees

Guarantee	Status
Readonly-first engineering analysis	Enforced
Mutation preflight before writes	Enforced
Human approval for governed execution	Required
Browser capture policy tiers	Enforced
Audit artifacts for evidence operations	Generated
Unrestricted shell / auto-merge	Blocked

Quick start (manual)

git clone https://github.com/pilotmain/AethOS.git
cd AethOS
cp .env.example .env
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn aethos_core.api.main:app --reload --port 8010

cd web
echo 'NEXT_PUBLIC_API_BASE=http://127.0.0.1:8010' > .env.local
npm install && npm run dev

See docs/SETUP.md for provider keys, browser automation, and Telegram.

Documentation

Doc	Topic
Documentation index	Supported user, operator, and developer guides
Installation	One-command install, resume, Windows, upgrades
Setup	Full install and environment
Brand & install experience	Visual identity, terminology, onboarding
Architecture	System design
Runtime	Chat lanes, jobs, orchestration
Testing	Test strategy

Development

pytest tests/ -q
cd web && npm test -- --run

Reliability gate: pytest tests/test_chat_20_turn.py -q

Before opening a pull request, read CONTRIBUTING.md. All contributions require review, passing checks, and a DCO sign-off. Project roles and decisions are described in GOVERNANCE.md.

License

AethOS is open source under the Apache License 2.0. See LICENSING.md and COPYRIGHT.md for scope, attribution, and contributor ownership.

AethOS — confidence at first command.

Name		Name	Last commit message	Last commit date
.github		.github
aethos_core		aethos_core
aethos_sdk		aethos_sdk
deploy		deploy
docs		docs
provider_skills		provider_skills
scripts		scripts
skills		skills
tests		tests
web		web
.env.example		.env.example
.env.selfhost.example		.env.selfhost.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.gitleaksignore		.gitleaksignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYRIGHT.md		COPYRIGHT.md
COVERAGE_MATRIX.md		COVERAGE_MATRIX.md
DCO.md		DCO.md
DISCLAIMER.md		DISCLAIMER.md
Dockerfile		Dockerfile
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
LICENSING.md		LICENSING.md
MEMORY.md		MEMORY.md
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
SOUL.md		SOUL.md
SUPPORT.md		SUPPORT.md
VERSION		VERSION
docker-compose.local.yml		docker-compose.local.yml
docker-compose.prod.yml		docker-compose.prod.yml
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
requirements.lock		requirements.lock
run.ps1		run.ps1
run.sh		run.sh

Navigation Menu

Repository files navigation

AethOS

What is AethOS?

Install AethOS

Architecture

Verified capabilities

Mission Control

Governance guarantees

Quick start (manual)

Documentation

Development

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AethOS

What is AethOS?

Install AethOS

Architecture

Verified capabilities

Mission Control

Governance guarantees

Quick start (manual)

Documentation

Development

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages