Skip to content

Horizon AIOS — Docker Deployment

Deploys the AIOS OS layer as a Docker container. Brains run as sub-containers (one container per brain) or as OS users within the AIOS container. See philosophy.md §5 for the conceptual model.

AIOS Docker images are Linux-container based (Ubuntu) and run on Windows, macOS, and Linux hosts via the container runtime (Docker Desktop / WSL2 on Windows and macOS, Docker Engine on Linux). Native Windows containers are out of scope. On a Windows host, drive the build/run path with bootstrap_docker.ps1 (PowerShell wrapper); on Linux/macOS use bootstrap_docker.sh. Both run inside Linux containers.

Status: Template only — not yet end-to-end verified. See tested_configurations.md.

Prerequisites

  • Docker Engine ≥24 and Docker Compose ≥2.20 installed on the host.
  • ANTHROPIC_API_KEY set in your environment (or a .env file in the deployment directory).
  • The Horizon AIOS repo cloned to the host.

Quick Start

All commands run from $HORIZON_ROOT (the repo root).

# Build the AIOS image
docker build \
  -f horizon_system/templates/docker/Dockerfile \
  -t horizon-aios \
  .

# Start the AIOS container
docker compose \
  -f horizon_system/templates/docker/docker-compose.yml \
  up -d

# Open an interactive Claude Code session inside the container
docker exec -it horizon-aios claude

Volumes and Mutable State

The Docker image bakes in the AIOS layer (repo contents + bootstrap). Mutable state must be volume-mounted from the host to persist across container restarts and rebuilds.

Volume / Mount Default (named volume) Notes
/aios/horizon_system/logs aios-logs Audit and operational logs
/aios/handoffs aios-handoffs Session handoff documents
/aios/objectives aios-objectives Durable multi-session objectives
/aios/brains Host path (commented out) Brain directories — set HOST_BRAINS_PATH in compose file

Edit horizon_system/templates/docker/docker-compose.yml to mount host paths before starting.

Objectives persistence

The /objective skill stores durable, multi-session goals in $HORIZON_ROOT/objectives/ (i.e. /aios/objectives/ in the container). The compose template mounts this directory as the aios-objectives named volume, so objectives persist across container restarts and rebuilds.

/handoff is similarly backed by the aios-handoffs named volume.

Brain Isolation in Docker

Current state (supported): The AIOS Dockerfile and compose template run one aios service with all brains operating as OS user accounts inside that container — the same model as a native OS deployment. Brain isolation is enforced by OS user boundaries and POSIX permissions within the container. This is the supported and tested Docker deployment model.

Per-brain container isolation (user-owned): If your threat model requires each brain to be isolated at the container boundary — not just the OS user boundary — this is a valid architectural choice, but it is user-owned. AIOS does not provision or manage per-brain containers. The pattern is:

  1. Create one docker-compose service per brain, mounting only that brain's directory ($HORIZON_ROOT/brains/<name>/) as a writable volume.
  2. Mount $HORIZON_SYSTEM/skills_bin read-only into each brain container for shared skill access.
  3. Mount $HORIZON_SYSTEM read-only (or a subset) for shared AIOS config; do not mount sbin/ or skills_sbin/.
  4. Each brain container gets its own Claude Code install and ~/.claude/ config derived from the brain's AIOS settings template (brains/.aioscommon/brain_settings.json.template).
  5. Inject brain credentials via environment variables or a secrets manager; do not share the host OS credential store across containers.
  6. The AIOS audit log volume (aios-logs) must not be mounted into any brain container.

See philosophy.md §5 for the deployment model overview.

Audit trail in Docker: The AIOS container's audit log volume (aios-logs) must not be accessible to brain containers. Do not mount it into brain service definitions.

Rebuilding After AIOS Updates

The AIOS layer is baked into the image. After pulling a new version of the repo:

docker compose -f horizon_system/templates/docker/docker-compose.yml build
docker compose -f horizon_system/templates/docker/docker-compose.yml up -d

Named volumes (aios-logs, aios-handoffs, aios-objectives) persist across rebuilds. Host-mounted brain and key directories are unaffected.

BYOH — Swapping the Harness

Claude Code is the default harness in the Dockerfile. To use a different harness:

  1. Remove the Node.js and npm install -g @anthropic-ai/claude-code blocks from the Dockerfile.
  2. Add your harness installation commands in their place.
  3. Update the CMD line to launch your harness, or leave it as ["bash"] and invoke the harness via docker exec.

The AIOS OS layer (env vars, bootstrap, skills, audit hooks, brain isolation) is harness-agnostic.

Known Gaps

  • horizon_aios_create_brain.py is not yet adapted for Docker — it provisions OS user accounts, not Docker containers. Brain container provisioning is currently manual (duplicate the compose service template).
  • bootstrap_docker.sh (and the bootstrap_docker.ps1 Windows-host wrapper) runs the standard bootstrap; the skills symlink (~/.claude/skills/ → skills_sbin/) is created but not verified in a full session.
  • Sync schedule (horizon_aios_setup_sync_schedule.py) is skipped in Docker mode. AIOS updates are delivered by rebuilding the image.
  • The images are Linux containers and run on Windows/macOS/Linux hosts via the container runtime; Linux host is the only host end-to-end verified so far. Windows and macOS hosts (Docker Desktop / WSL2) run the same Linux images but have not been verified.