feat: Docker image + compose for the whole nine-project stack

One container runs everything: Python/uv, Node 22/pnpm, Bun, the Claude CLI,
ripgrep and yt-dlp, driven by `aios` exactly as on the host.

    docker compose up -d --build   ->  http://localhost:8787

Containerising this is more than convenience. AIOS gives every agent full control
of the machine it runs on; in a container that machine is a blast radius you can
delete. Guardrails and the hub token still apply inside, so it's defence in depth
rather than a swap: no-new-privileges, SYS_ADMIN/NET_ADMIN dropped, and the hub
binds 0.0.0.0 only because non-loopback requests need AIOS_HUB_TOKEN — which the
entrypoint mints on first boot and prints with the URL.

State survives rebuilds: .aios (memory, tasks, flows, audit) is a named volume,
.env / aios.config.yaml bind-mount from the repo, and ~/.claude mounts through so
the claude-code service inherits a host login (or run `aios claude-login` inside).

Two bugs found by building it for real:
- Installing from package.json alone silently produced EMPTY node_modules for
  opencode and openclaw — both are workspace monorepos needing full source to
  resolve, and the `|| true` hid it. The image now lets `aios setup` install,
  since it already encodes every workaround (--ignore-scripts for native
  postinstalls, NODE_OPTIONS heap sizing for openclaw's build, uv sync).
- The image came out 16.2GB. pnpm's content-addressable store was 4.7GB and the
  caches ~1GB; because pnpm hardlinks node_modules into the store, dropping it
  frees the space while the linked files stay intact — verified in-container
  before baking it in, and done in the same layer so the bytes actually go.

Also fixes a gap this exposed: `aios update` mounted LifeOS/OpenUI/AIOS skills but
not the caveman, ponytail and ruflo ones that `aios setup` mounts, so updating left
those stale. Both paths now mount the same set.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ZD Studios

.dockerignore

@@ -0,0 +1,39 @@
+# The repo carries nine vendored projects; without this the build context is
+# gigabytes of node_modules and git history that the image rebuilds anyway.
+.git
+**/.git
+**/node_modules
+**/.venv
+**/venv
+**/__pycache__
+**/*.pyc
+**/.pytest_cache
+**/.mypy_cache
+**/.ruff_cache
+**/dist
+**/build
+**/.next
+**/.turbo
+**/target
+
+# Local state and secrets — mounted at runtime, never baked into the image.
+.aios/
+.env
+*.env
+!.env.example
+aios.config.yaml
+
+# Host-specific junk
+.claude/
+.vscode/
+.idea/
+*.log
+*.zip
+*.tar.gz
+Thumbs.db
+.DS_Store
+
+# Docs/media that don't affect the runtime
+docs/aios/inventory.md
+**/*.gif
+**/*.mp4

Dockerfile

@@ -0,0 +1,97 @@
+# syntax=docker/dockerfile:1
+# ─────────────────────────────────────────────────────────────────────────────
+# The AI OS — containerised.
+#
+# Nine open-source AI projects across three runtimes (Python/uv, Node/pnpm, Bun)
+# in one image, driven by `aios`.
+#
+#   docker compose up -d          then open http://localhost:8787
+#
+# Why a container is the *right* place to run this: The AI OS gives every agent
+# full control of the machine it runs on — shell, filesystem, network. On your
+# laptop that means your laptop. Here it means this container, which is a blast
+# radius you can delete. Guardrails and the hub token still apply inside.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ---------- stage 1: toolchains ---------------------------------------------
+FROM python:3.12-slim-bookworm AS base
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    NODE_MAJOR=22 \
+    PNPM_HOME=/usr/local/pnpm \
+    BUN_INSTALL=/usr/local/bun \
+    PATH=/usr/local/pnpm:/usr/local/bun/bin:/root/.local/bin:$PATH
+
+# Node 22 (openclaw + Next.js need >=20), plus the build deps native modules want.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates curl git unzip xz-utils ripgrep procps tini \
+        build-essential python3-dev \
+    && curl -fsSL https://deb.nodesource.com/setup_${NODE_MAJOR}.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && npm install -g pnpm@9 \
+    && curl -fsSL https://bun.sh/install | bash \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && apt-get purge -y --auto-remove \
+    && rm -rf /var/lib/apt/lists/* /tmp/*
+
+# Claude Code CLI — powers the claude-code service (subscription auth, no API key).
+RUN npm install -g @anthropic-ai/claude-code || \
+    echo "claude CLI unavailable at build time; install later with: npm i -g @anthropic-ai/claude-code"
+
+# yt-dlp powers YouTube transcripts (the caption endpoint needs a PO token).
+RUN pip install --no-cache-dir --upgrade yt-dlp
+
+# ---------- stage 2: runtime ------------------------------------------------
+FROM base AS runtime
+WORKDIR /aios
+
+LABEL org.opencontainers.image.title="The AI OS" \
+      org.opencontainers.image.description="Nine open-source AI projects. One operating system." \
+      org.opencontainers.image.source="https://github.com/ZDStudios/AIOS" \
+      org.opencontainers.image.licenses="MIT"
+
+COPY . /aios
+
+# `aios setup` does the installing rather than a hand-written RUN, because it
+# already encodes every per-project workaround: --ignore-scripts for the native
+# postinstalls that need VS Build Tools, NODE_OPTIONS heap sizing for openclaw's
+# build, and uv sync for the Python projects. Installing from package.json alone
+# silently produces empty node_modules — opencode and openclaw are workspace
+# monorepos and need their full source present to resolve.
+RUN set -eux; \
+    cp -n aios.config.example.yaml aios.config.yaml 2>/dev/null || true; \
+    chmod +x aios docker/entrypoint.sh 2>/dev/null || true; \
+    mkdir -p /aios/.aios; \
+    python aios.py setup --non-interactive --skip-keys --skip-tools --skip-wire \
+      || echo "setup reported warnings — see 'docker compose exec aios aios doctor'"; \
+    # Same layer as the install, or the image keeps the deleted bytes anyway.
+    # pnpm hardlinks node_modules into its content-addressable store, so dropping
+    # the store frees ~4.7GB while the linked files stay intact (verified).
+    rm -rf /usr/local/pnpm/store /root/.cache /root/.npm /tmp/* /var/tmp/*; \
+    find /aios -type d -name ".git" -prune -exec rm -rf {} + 2>/dev/null || true; \
+    apt-get purge -y --auto-remove build-essential python3-dev 2>/dev/null || true; \
+    rm -rf /var/lib/apt/lists/*
+
+# Login shells (docker exec ... bash) re-read /etc/profile and would otherwise
+# lose the toolchain PATH baked into ENV.
+RUN printf 'export PATH=/usr/local/pnpm:/usr/local/bun/bin:/root/.local/bin:$PATH\n' \
+      > /etc/profile.d/aios-path.sh
+
+ENV AIOS_ROOT=/aios \
+    AIOS_HUB_HOST=0.0.0.0 \
+    AIOS_IN_DOCKER=1 \
+    AIOS_NO_UPDATE_CHECK=1
+
+#   8787 hub · 4096 opencode · 9119 hermes · 18789 openclaw
+#   4788 crewai · 8000 claude-code · 8791/8792 embed proxies
+EXPOSE 8787 4096 9119 18789 4788 8000 8791 8792
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=180s --retries=5 \
+    CMD curl -fsS http://127.0.0.1:8787/health || exit 1
+
+# tini reaps the process trees aios spawns, so stopping the container doesn't
+# strand bun/node/uv children as zombies.
+ENTRYPOINT ["/usr/bin/tini", "--", "/aios/docker/entrypoint.sh"]
+CMD ["start"]

README.md

@@ -66,6 +66,16 @@ curl -fsSL https://raw.githubusercontent.com/ZDStudios/AIOS/main/install.sh | ba
 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:
+
+```bash
+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](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**)

aios.py

@@ -1593,6 +1593,8 @@ def cmd_update(args):
         mount_openui(cfg)
     if cfg_get(cfg, "skills.mount", True):
         mount_aios_skills(cfg)
+        mount_agent_modes(cfg)  # caveman + ponytail — same set setup mounts
+        mount_ruflo(cfg)
     # Restart any services that are currently running so the new code takes effect.
     specs = service_specs(cfg)
     running = [s for s in specs if (read_pid(s) and pid_alive(read_pid(s)["pid"]))]

docker-compose.yml

@@ -0,0 +1,62 @@
+# The AI OS — one container, nine AI projects.
+#
+#   docker compose up -d --build      build and start
+#   docker compose logs -f            watch it come up (first boot takes a while)
+#   docker compose exec aios aios status
+#   docker compose exec aios aios claude-login    use your Claude subscription
+#
+# Then open http://localhost:8787 — the token is printed in the logs.
+
+services:
+  aios:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: ghcr.io/zdstudios/aios:latest
+    container_name: aios
+    restart: unless-stopped
+    ports:
+      - "8787:8787"      # ★ Control Room (the only one you normally need)
+      - "4096:4096"      # opencode
+      - "9119:9119"      # hermes
+      - "18789:18789"    # openclaw gateway (+ openclaw-os dashboard)
+      - "4788:4788"      # CrewAI
+      - "8000:8000"      # claude-code API
+      - "8791:8791"      # openclaw embed proxy
+      - "8792:8792"      # hermes embed proxy
+    environment:
+      # One provider key powers every agent. Leave blank and use your Claude
+      # subscription instead (docker compose exec aios aios claude-login).
+      AIOS_LLM_PROVIDER: "${AIOS_LLM_PROVIDER:-openrouter}"
+      AIOS_LLM_API_KEY: "${AIOS_LLM_API_KEY:-}"
+      AIOS_DEFAULT_MODEL: "${AIOS_DEFAULT_MODEL:-anthropic/claude-opus-4.6}"
+      # Raises the GitHub API limit for supervised updates (60/hr -> 5000/hr).
+      GITHUB_TOKEN: "${GITHUB_TOKEN:-}"
+      AIOS_HUB_HOST: "0.0.0.0"
+    volumes:
+      # Durable state: memory, tasks, flows, audit log, pidfiles, logs.
+      - aios-state:/aios/.aios
+      # Secrets + config on the host, so rebuilds don't lose them.
+      - ./.env:/aios/.env
+      - ./aios.config.yaml:/aios/aios.config.yaml
+      # Your Claude CLI login, so the claude-code service is authenticated.
+      # Comment this out if you'd rather log in inside the container.
+      - ${HOME:-~}/.claude:/root/.claude
+    # Agents get full control of this container. That's the point — and the
+    # container boundary is what makes it a reasonable thing to hand them.
+    # These caps are dropped anyway; nothing AIOS runs needs them.
+    cap_drop:
+      - SYS_ADMIN
+      - NET_ADMIN
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8787/health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 180s
+      retries: 5
+    stop_grace_period: 30s
+
+volumes:
+  aios-state:

docker/entrypoint.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# The AI OS container entrypoint.
+#
+#   start   (default)  render config, bring the stack up, stay in the foreground
+#   setup              re-run setup (deps/build/wire) then exit
+#   shell              a shell inside the container
+#   <anything else>    passed straight to `aios`
+set -euo pipefail
+
+cd /aios
+export PATH="/usr/local/pnpm:/usr/local/bun/bin:/root/.local/bin:$PATH"
+
+c(){ printf '\033[1;36m%s\033[0m\n' "$*"; }
+ok(){ printf '\033[1;32mOK\033[0m %s\n' "$*"; }
+warn(){ printf '\033[1;33m!\033[0m %s\n' "$*"; }
+
+# .aios/ and .env come from volumes, so a fresh container inherits your state.
+mkdir -p /aios/.aios
+[ -f /aios/aios.config.yaml ] || cp aios.config.example.yaml /aios/aios.config.yaml
+
+# The hub binds 0.0.0.0 so the port publish works. That is only safe because
+# non-loopback requests need the token — mint it before anything starts.
+if [ ! -f /aios/.env ] || ! grep -q '^AIOS_HUB_TOKEN=' /aios/.env 2>/dev/null; then
+  python aios.py token >/dev/null 2>&1 || true
+fi
+TOKEN="$(grep -m1 '^AIOS_HUB_TOKEN=' /aios/.env 2>/dev/null | cut -d= -f2- || true)"
+
+case "${1:-start}" in
+  start)
+    c "The AI OS — starting in Docker"
+    if [ -z "${AIOS_LLM_API_KEY:-}" ] && ! grep -q '^AIOS_LLM_API_KEY=.\+' /aios/.env 2>/dev/null; then
+      warn "no model API key set — the stack will run, but agents can't answer."
+      warn "Set one in .env / compose env, or use your Claude subscription:"
+      warn "  docker compose exec aios aios claude-login"
+    fi
+
+    # Render .env + config into every project, mount skills, apply exec policy.
+    python aios.py setup --non-interactive --skip-tools --skip-install \
+      || warn "setup finished with warnings (run: docker compose exec aios aios doctor)"
+
+    python aios.py start all --timeout 180 || warn "some services did not report healthy"
+    python aios.py status || true
+
+    echo
+    ok "Control Room:  http://localhost:8787/${TOKEN:+?token=$TOKEN}"
+    [ -n "$TOKEN" ] && echo "   hub token: $TOKEN"
+    echo
+
+    # PID 1 must stay alive for the container to stay up. Watch the hub and
+    # surface its log, so `docker logs` shows something useful.
+    touch /aios/.aios/logs/hub.log 2>/dev/null || mkdir -p /aios/.aios/logs
+    tail -n 0 -F /aios/.aios/logs/*.log 2>/dev/null &
+    while true; do
+      if ! curl -fsS http://127.0.0.1:8787/health >/dev/null 2>&1; then
+        warn "hub stopped responding — restarting it"
+        python aios.py restart hub || true
+      fi
+      sleep 20
+    done
+    ;;
+  setup)  shift; exec python aios.py setup --non-interactive "$@" ;;
+  shell)  exec /bin/bash ;;
+  *)      exec python aios.py "$@" ;;
+esac