🧠 The AI OS

Eleven open-source AI projects. One operating system. One Control Room.

Install · Control Room · Architecture · Commands · Full docs · Website

---

The AI OS takes eleven independent open-source AI projects and makes them work as one auto-configured system you drive from a single command — aios — and a single web Control Room where you can talk to everything and have the agents talk to each other.

One control script. One config. One .env. aios setup installs every toolchain, wires the projects together, mounts your shared skills, and adds OpenUI generative-UI context to every agent. aios start brings the whole stack up behind the Control Room dashboard.

You can't fuse three runtimes and multiple package managers into a single file — that would just break everything. So "one file" here means one control surface (aios) + one dashboard (the Hub) over eleven real, unmodified projects. It installs, configures, wires, runs, tests, and debugs all of them.

aios setup   →   aios start   →   aios url        (opens the Control Room)

⚡ Install (one line)

Linux / macOS / WSL:

curl -fsSL https://raw.githubusercontent.com/ZDStudios/AIOS/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/ZDStudios/AIOS/main/install.ps1 | iex

Docker — no toolchains on your machine, and the agents' full control is scoped to a container you can delete:

git clone https://github.com/ZDStudios/AIOS.git && cd AIOS
cp .env.example .env          # add a model key, or use your Claude subscription
docker compose up -d --build  # then open http://localhost:8787

Full guide: docs/DOCKER.md.

The installer asks for root once, up front (sudo on Linux/macOS, a UAC prompt on Windows) — because the agents get full control of the machine and setup registers a start-on-boot service and a global aios command. It then clones the repo to ~/AIOS, installs the toolchains (uv, bun, pnpm, Node) into your user profile, and runs aios setup — installing every agent's deps, building, wiring the Control Room, and applying the full-control exec policy. Then add your key:

cd ~/AIOS
./aios install-cli       # so `aios` runs from anywhere (no ./)
aios setup --force       # enter your model provider + API key (or skip)
aios start               # bring the whole stack up
aios url                 # open the Control Room

aios install-cli adds aios to your PATH (~/.local/bin), so after that you can run aios update, aios start, etc. from any directory. aios setup also offers to do this.

💬 The Control Room

aios start launches the AIOS Hub — a single web dashboard at http://127.0.0.1:8787/ where you can:

• Talk to everything — chat with the Brain (orchestrator), CrewAI (multi-agent crews), opencode (coding), or broadcast to all at once.
• See everything live — real-time health of every service.
• Use every agent's UI — the hermes and openclaw-os dashboards are embedded as tabs.
• Let agents reach each other — the Hub is the interconnect bus; each agent is given every other agent's endpoint, and CrewAI ships an ask_peer tool to call them.
• Render generative UI (OpenUI) in the hub — any agent can emit a ui block (self-contained HTML) that the hub renders live and interactive in chat (sandboxed, theme-aware). openclaw-os also renders OpenUI Lang natively.
• Shared Canvas any agent can edit — agents POST /api/ui (CrewAI has a build_dashboard_ui tool) to pin widgets to a Canvas everyone sees. This is how "all agents edit the dashboard."

🧩 The agents

Agent	Role in The AI OS	Port	Upstream
opencode	Coding-agent engine (headless server + SDK)	4096	opencode.ai
hermes	Autonomous agent — memory, cron, learning loop, dashboard	9119	Nous Research
openclaw	Multi-channel messaging gateway + plugin host	18789	openclaw.ai
CrewAI	Multi-agent orchestration — role-based crews	4788	crewaiinc/crewai
claude-code	Claude Code as an OpenAI-compatible API	8000	codingworkflow/claude-code-api
Codex	OpenAI Codex CLI as an OpenAI-compatible API — your ChatGPT sub, no API key	8010	openai/codex
Paperclip	The company layer — org chart, tickets, heartbeats, budgets, governance	3100	paperclipai/paperclip
LifeOS	Shared identity + skills mounted into the agents	—	danielmiessler/LifeOS

Plus the integrations that glue it together — these aren't services, they're mounted into every agent:

	Role	Upstream
AIOS Hub	The Control Room — unified dashboard + interconnect (:8787)	(this repo)
openclaw-os	openclaw's generative-UI dashboard (a plugin, not an agent)	thesys
OpenUI	Generative-UI standard, mounted into every agent	openui.com
Fabric	255 task patterns run on your own model — summarize, extract_wisdom, …	danielmiessler/fabric
Caveman	Conciseness mode — ~65% fewer output tokens, accuracy kept	JuliusBrussee/caveman
Ponytail	Laziness mode — ~54% less code, YAGNI enforced	DietrichGebert/ponytail
Ruflo	Agent meta-harness — swarms, 314+ MCP tools, 30+ plugins	ruvnet/ruflo

🗺️ Architecture

        ┌────────────────────────────────────────────────────────────────────┐
        │  💬  AIOS Hub — the Control Room  :8787                             │
        │  chat · canvas · task brain · taskflow · updates · audit · REST API │
        └──┬────────┬────────────┬────────────┬────────────┬─────────────────┘
           │        │            │            │            │   agents reach each other
   ┌───────▼──┐ ┌───▼──────┐ ┌───▼──────┐ ┌───▼──────┐ ┌───▼─────────┐  through the Hub
   │ opencode │ │ hermes   │ │ openclaw │ │ CrewAI   │ │ claude-code │
   │  :4096   │ │  :9119   │ │  :18789  │ │  :4788   │ │   :8000     │
   │ coding   │ │autonomous│ │28 channels│ │  crews   │ │ your Claude │
   └──────────┘ └────┬─────┘ └────┬─────┘ └──────────┘ │subscription │
                     │            │ hosts              └─────────────┘
              ┌──────▼────────────▼──────┐
              │ embed proxies :8791/:8792│  so their UIs render inside the Hub
              └──────────┬───────────────┘
                    ┌────▼─────────────────┐
                    │ openclaw-os (OpenUI) │  generative-UI dashboard
                    └──────────────────────┘
   ┌────────────────────────────────────────────────────────────────────────┐
   │ Mounted into EVERY agent — not services:                               │
   │  LifeOS skills · OpenUI context · Fabric (255 patterns)                │
   │  Caveman (say less) · Ponytail (build less) · Ruflo (swarms, MCP)      │
   └────────────────────────────────────────────────────────────────────────┘

  Single source of truth:  aios.config.yaml + .env  →  rendered into each project
  Single control surface:  aios <command>           →  state in .aios/aios.db
  Or run the whole thing:  docker compose up -d

✨ What you get

One Control Room	Talk to every agent — or all at once — from one dashboard, and watch them talk to each other.
One command to rule them all	aios setup installs bun / pnpm / uv / Node, every agent's deps, builds what needs building, and wires it together. Idempotent.
One key, every agent	Set your provider + API key once in .env; aios maps it into all five.
Agents that reach each other	The Hub is a shared bus; each agent knows every peer's endpoint. CrewAI ships an ask_peer tool.
Generative UI everywhere	OpenUI context is mounted into every agent; openclaw-os renders the results as live apps.
Doctor + smoke tests	aios doctor prints the exact fix for any problem; aios test --smoke drives the whole stack.
Windows-first, cross-platform	Built and verified on Windows 11 (PowerShell), with POSIX / macOS / Linux / WSL parity.

🎛️ Command reference

Command	What it does
aios setup	Guided install: toolchains + deps, key wizard (or --skip-keys), render, build, mount, wire. Offers autostart + "start now".
aios setup --skip-keys	Skip the API-key wizard entirely — the stack still runs; add keys later in the hub Settings panel.
aios start [svc…|all]	Start service(s) (opencode hermes openclaw crewai hub), wait on health checks. Accepts multiple names.
aios stop [svc…|all]	Stop service(s); kills the whole process tree — no orphans.
aios restart [svc…|all]	Force a clean respawn (picks up new code after an update). aios update does this automatically.
aios status	Table of each service: state, port, PID, health.
aios doctor	Diagnose tools, config, deps and ports — with the exact fix for each.
aios update [--check]	git pull + reinstall changed deps + re-render + re-mount skills. --check just reports if updates exist (also auto-checked on start).
aios paperclip [status|setup|task|open|install]	The company layer: hire every agent into a Paperclip org chart, file tickets, open its board.
aios updates [--apply P]	Supervised upstream updates — an agent reviews the commits and returns SAFE/RISKY/BLOCK before anything is applied; --rollback P restores a previous version.
aios autostart enable|disable	Run The AI OS on login/boot (Startup shortcut on Windows, systemd/.bashrc on Linux/WSL).
aios exec <cmd>	Run a command through the agents' own guardrailed, audited shell.
aios channels	List the 28 messaging channels the gateway can bridge, and which are configured.
aios attach [args]	Jump into a running OpenClaw gateway session with an external harness, mid-run.
aios migrate [--source]

In the Control Room (http://127.0.0.1:8787/) you can:

• Chat with any agent (Brain, CrewAI, opencode, claude-code) or broadcast to All.
• ✦ Team — one assistant that orchestrates the whole team: the Brain plans, delegates subtasks to the specialist agents, and synthesizes one answer (the practical "merge").
• Configure openclaw AND hermes fully inside the hub — both control-UIs are embedded via frame-stripping proxies, so you get channels, connectors, model providers, MCP servers, skills, plugins, automations/cron, and sessions right in the hub (they normally block embedding).
• Automations — schedule prompts to run against any agent every N minutes (daily digests, checks).
• Log in to Claude from the dashboard — Settings → "1 · Log in to Claude" runs the Claude CLI login through the hub: it shows the authorize link, you approve in the browser and paste the code back, all in the UI. Then "2 · Use my Claude subscription" routes the Brain/Team/crews through claude-code (no API key, no per-token cost). A live status line shows whether claude-code is up and actually authenticated. (Terminal equivalent: aios claude-login.)
• 🛡️ Self-healing agents — a watchdog in the hub health-checks every agent. If one stops responding it's automatically restarted; if the restart fails, a healthy agent reads its logs and diagnoses the cause. See the incident log in Status → Self-healing log (watchdog.enabled in aios.config.yaml).
• 📡 Channels — a grid of every messaging app OpenClaw can bridge (WhatsApp, Telegram, Discord, Slack, Signal, Matrix, Teams, iMessage, …). Paste a channel's token and it goes live on the one gateway daemon.
• ⚙ Task Brain — one SQLite-backed scheduler for cron jobs, interval prompts, and background shell commands. Every run is recorded; tasks survive restarts.
• 🔀 TaskFlow — durable multi-step flows that chain agents. State is committed after every step, so a crash or restart resumes where it left off instead of replaying work.
• 🎓 Skills — install ClawHub-style skills, and watch the self-improving loop: after a task that ran commands, a Curator judges whether it taught a reusable procedure and writes a SKILL.md every agent then mounts.
• 🛡️ Control & Audit — see full-control status, run a guardrailed command, and read the of every command any agent ran on this machine.

Auto-updates: aios start now auto-runs git pull + reinstalls changed deps when the repo has updates (updates.auto_update: true). Turn it off in aios.config.yaml.

✨ 10 things no single-agent tool can do

Because The AI OS runs six agents wired through one hub, it can do multi-agent things nothing else can:

1. 🎯 Auto-router — the hub reads your message and automatically picks the best agent (code → opencode, research → CrewAI…), and tells you which it chose.
2. ⚖️ Agent Arena — send one prompt to two agents side-by-side and compare their answers.
3. 🏛️ Council — ask several agents, then a chair agent synthesizes a consensus and flags where they disagree.
4. ⛓ Pipelines — chain agents: research (CrewAI) → build (opencode) → summarize (Brain), each step feeding the next.
5. 🧠 Shared memory — facts you save are injected into every agent's context, so they all know you.
6. 📚 Prompt library + slash commands — save prompts, type /name in chat to expand them.
7. 🎙️ Voice in/out — talk to the hub and have replies read aloud (browser-native, no cloud).
8. ⌘K command palette — jump anywhere or ask any agent instantly.
9. 📊 Usage + subscription-savings meter — counts requests per agent and shows how many ran free on your Claude subscription.
10. ⬇️ Export & saved conversations — full conversation history (pinned/today/earlier), export any chat to Markdown.

AIOS API (OpenAI-compatible): the hub is itself an API you can POST to. Point any OpenAI client/SDK at http://<host>:8787/v1. The "models" are the agents/targets: brain, team, opencode, crewai, claudecode, all.

curl http://127.0.0.1:8787/v1/chat/completions -H "Content-Type: application/json" \
  -d '{"model":"team","messages":[{"role":"user","content":"build a todo app and research frameworks"}]}'

curl http://127.0.0.1:8787/v1/models         # list targets
# or the simple form:  POST /api/chat {"target":"brain","message":"hi"}

Model picker: in Settings, click ↻ fetch my models to pull the live model list from your provider (e.g. all your Claude models) and pick one.

Chat is now a 3-column workspace — conversation history (pinned / today / earlier) · transcript · live agent panel — with saved conversations.

/dry cost estimator: type /dry <your message> in chat to estimate the tokens and cost before running — using live per-model pricing (and $0 when on your Claude subscription). Multi-agent modes (Arena/Council/Pipeline) account for the extra calls.

Refined theming + theme store: the default is a warm, classical Hermes theme (charcoal + gold, serif headings) — plus OpenClaw (coral), Olympus (light), Obsidian, Forest, and Rose. Settings → Theme store lets you preview and apply any theme, or install your own by pasting a JSON of CSS variables.

Skills & system prompt: 10 skills ship built-in (skill-maker, mcp-maker, web-search, web-browse, image-gen, code-review, summarize, research, data-analyst, task-scheduler) and mount into every agent. Edit the Brain/Team system prompt live in the hub → Settings.

🖥️ Full machine control (and how it's kept safe)

Every agent controls the computer The AI OS is installed on — shell, filesystem, network — through each project's own supported switch (opencode OPENCODE_PERMISSION, claude-code --dangerously-skip-permissions, OpenClaw exec-policy preset yolo, Hermes unattended-approval, plus a RUN: tool-loop the Brain drives). The installer asks for root once, up front to set the system pieces up in one pass. Turn it all off with security.full_control: false.

That is deliberately the "ambient authority" posture that made OpenClaw's CVE-2026-25253 a critical RCE — so full control is paired with a real gate, not left open:

• Loopback is trusted; everyone else needs a token. The hub mints AIOS_HUB_TOKEN at setup. Binding to 0.0.0.0 (needed for WSL) is only safe because every non-loopback request must carry it — aios url prints the token link.
• CSRF is closed. A page on the internet can reach http://127.0.0.1:8787 from your browser, so cross-origin requests are rejected unless they carry the token, and CORS never echoes *.
• DNS-rebinding is closed. The Host header must be an IP literal or a known-local name.
• Guardrails still refuse the handful of commands that wreck the host rather than do the task — rm -rf /, mkfs, dd to a block device, fork bombs, shutdown (security.guardrails: false to disable).
• Everything is audited. Every command any agent runs is written to .aios/aios.db and shown in Control & Audit.

Active Memory: a memory sub-agent runs on every turn — recall is a free FTS5 query, fact-extraction is one small async call — so the agents actually learn your workflow over time instead of only reading memory at session start (memory.active).

🌐 It can actually read the web

Paste a link and the agents read it — no API keys, no "I can't open URLs".

Source	What you get
YouTube	Full transcript (flat, timestamped, or segment objects), title, channel, duration, views, description, chapters, available languages
Reddit	A thread with its comment tree, a subreddit listing, or a search
Hacker News	Story search, or a story with its full comment thread
Any page	Reduced to clean readable text
Search	DuckDuckGo, no key

aios web youtube "https://youtu.be/VIDEO_ID"      # transcript in your terminal
aios web reddit  "r/LocalLLaMA"                   # or a thread URL, or a search
aios web fetch   "https://example.com/article"

In chat: /yt <url>, /reddit <target>, /hn <query>, /web <url> — or just paste a link and ask; the Brain calls POST /api/web itself. The bundled web-research skill teaches every agent the same API.

Two honest caveats, both surfaced in the response rather than hidden:

• YouTube transcripts need yt-dlp (aios setup installs it). YouTube now serves its caption endpoint an empty body unless the request carries a proof-of-origin token, so scraping it directly no longer works — yt-dlp is what keeps up with that. Without it you still get metadata, and the note tells you what to install.
• Reddit blocks its JSON API from many networks, so AIOS falls back to RSS automatically. When that happens the response says "source":"rss" and scores are null — the agents are told not to report vote counts they didn't actually get. Reddit also rate-limits hard, so calls are throttled and retried.

🤖 Ruflo — heavyweight orchestration on demand

ruvnet/ruflo is an agent meta-harness: multi-agent swarms, 314+ MCP tools, vector memory, federation, and 30+ plugins. AIOS ships its skills and plugin catalogue and drives the runtime from npm, so it's always current.

aios ruflo plugins         # the 30+ plugins and their skill counts
aios ruflo init wizard     # set it up inside a project
aios ruflo mcp-register    # register its MCP server with Claude Code
aios ruflo <anything>      # passed through to `npx ruflo@latest`

AIOS is the always-on system (services, channels, dashboard, Task Brain); ruflo is a per-project harness you invoke for a heavy job. They compose.

🏢 Paperclip — run the agents as a company

paperclipai/paperclip models agents as employees: an org chart, tickets with a status machine, heartbeats that wake an agent when it has work, monthly budgets and board governance. AIOS runs it as a service on :3100 and hires its own agents into it, so work handed to "the company" is tracked the same way a team tracks work.

aios paperclip setup          # create "The AI OS" company and hire the team (idempotent)
aios paperclip task "Audit the auth module for injection bugs"
aios paperclip status         # org chart + ticket counts
aios paperclip open           # Paperclip's own board in the browser

Paperclip seat	Who	How it runs
CEO	AIOS Brain	HTTP adapter → the hub → Brain/Team, which can delegate across every agent
CTO	opencode	HTTP adapter → the hub → opencode
Head of Research	CrewAI	HTTP adapter → the hub → CrewAI
Senior Engineer	Claude Code	Paperclip's native claude_local adapter, on your Claude login
Engineer	Codex	Paperclip's native codex_local adapter, on your ChatGPT login

How a ticket moves: Paperclip wakes the assignee with a heartbeat → the hub receives it at /api/paperclip/heartbeat, checks the ticket out, routes it to the right agent, posts the result as a comment and closes it (or marks it blocked with the reason, owned by the board). It all happens inside the heartbeat request, so Paperclip's run log matches what the agent actually did.

• Hub → Company view — the org chart, a live ticket board (to do / in progress / blocked / done), a new-ticket form, each ticket's comment thread, reopen/done/cancel, and Paperclip's own UI embedded.
• 🏢 Company chat chip — send any chat message as a ticket; the CEO takes it from there.
• Swarm history — finished swarms are mirrored into Paperclip as a parent ticket with one child per subtask (services.paperclip.mirror_swarms), so the company's record includes work done outside it.
• Zero setup — Paperclip needs Node 24; aios setup downloads a private Node 24 into .aios/runtime and installs paperclipai there. Your system Node is untouched. Its embedded Postgres and data live in .aios/paperclip. Mode is local_trusted (loopback only).
• Skills — Paperclip's own agent skills (paperclip, paperclip-board, paperclip-create-agent, paperclip-converting-plans-to-tasks) are mounted into every agent.

Windows notes, already handled: Paperclip's ACP engine can't spawn .cmd shims (Node's CVE-2024-27980 hardening), so AIOS uses its CLI engine and points it at the real codex.exe / claude.exe; Codex uses your real CODEX_HOME because Paperclip's per-company symlink seeding fails on Windows with EEXIST.

🎨 Agents can redesign the dashboard (safely)

Ask in chat — "make the accent blue and the text bigger", "hide Automations", "put a deploy-status panel on the dashboard" — and the agents do it through the hub API, never by editing dashboard.html. That's the point: styling lives in one server-side JSON document the page applies on top of your theme, so an agent can't break the UI by writing bad code, and one Reset undoes everything (Settings → Agent-applied appearance).

What they can change	How
Colours	any theme CSS variable — --accent, --bg, --text, --border…
Text size / density	scale 0.7–1.6, density compact | normal | comfortable
Custom CSS	appended last, for anything variables can't express
Sidebar	hide or reorder any nav item
OpenUI panels	self-contained agent HTML in sandboxed iframes, in the top, chat or sidebar slot

Changes appear within ~4s, survive a theme switch, and are audited. Hostile or careless input is refused, not applied: variable values containing { } < > ;, malformed keys, and CSS with @import, </style> or a remote url(http…) (which could beacon out) are rejected and reported back. The agents learn this from the bundled dashboard-designer skill, and the endpoint is GET/POST /api/dashboard (ops: set · nav · panel · reset).

🧵 Fabric patterns · 🗿 Caveman · 🎀 Ponytail

Three more open-source projects, wired in at the prompt level (no extra service to run):

• Fabric — 255 patterns. Fabric's "patterns" are curated system-prompts (summarize, extract_wisdom, analyze_claims, write_essay, create_quiz…). AIOS reads them straight from data/patterns/ and runs them on your configured model — including your Claude subscription — so there's no Go binary to install. Use them in the Patterns view (pick → paste → run) or inline in chat: /p summarize <text>. The fabric chat target also works: fabric with a message pattern: your text.
• Caveman — conciseness mode. A system-prompt overlay that makes every agent ~65% terser while keeping code, commands, and error strings exact. Toggle the 🗿 Caveman button in the composer (cycles off → lite → full → ultra → wenyan), or type /caveman [level] / /caveman off in chat. It's also mounted as a skill into opencode/hermes/openclaw, so they respect it too. Levels come straight from Caveman's own SKILL.md.
• Ponytail — build-less mode. The same idea applied to code instead of prose: a "laziness ladder" that forces the simplest thing that works (~54% less code, YAGNI enforced, stdlib before dependencies). Toggle 🎀 Ponytail in the composer or /ponytail [lite|full|ultra]. Caveman trims what an agent says; Ponytail trims what it builds — they compose, so you can run both.

On WSL? 127.0.0.1:8787 often won't reach WSL from your Windows browser (localhost-forwarding is flaky). aios start/aios url now print your WSL IP URL — use that (e.g. http://172.31.x.x:8787/). The hub binds 0.0.0.0 so the WSL IP always works.

⚙️ Configuration

• .env — secrets only (AIOS_LLM_PROVIDER, AIOS_LLM_API_KEY, AIOS_DEFAULT_MODEL, optional channel tokens). Git-ignored.
• aios.config.yaml — non-secret wiring (enabled services, ports incl. crewai: 4788 and hub: 8787, model routing, OpenUI/LifeOS mounting, health URLs). Copy from aios.config.example.yaml.

Edit one key in .env, run aios setup, and every agent — and the Hub, and CrewAI — is reconfigured. Full reference in README.aios.md.

🙏 Built on

The AI OS is an integration layer. All the heavy lifting is done by these open-source projects — go star them:

• opencode — the open-source AI coding agent
• hermes-agent by Nous Research — the self-improving agent
• openclaw — the personal AI assistant gateway
• CrewAI — framework for orchestrating role-playing, autonomous AI agents
• LifeOS by Daniel Miessler — the AI-powered life OS
• openclaw-os by thesys — the generative-UI dashboard
• OpenUI — the open standard for LLM-generated interfaces
• Paperclip — orchestration for zero-human companies
• Fabric, Caveman, Ponytail, Ruflo, Codex, claude-code-api

Each project keeps its own license (all MIT / open source); their LICENSE files ship unmodified.

📄 License

The aios orchestrator, Hub, and docs are released under the MIT License. Bundled projects retain their own licenses. See LICENSE.