Coleo

Appearance

Docker Guide ​

Use Docker when you want Coleo running as a self-hosted service instead of as local foreground processes.

Choose the Docker Path ​

Local or private host ​

This is the default and recommended starting point. It runs:

  • observatory (web UI + API)
  • brain
  • arm-agent (headless OpenCode arms)
  • nats
  • qdrant

Bring it up with:

bash
cp deploy/self-host/.env.hosting.example deploy/self-host/.env.hosting
./deploy/self-host/bin/bootstrap-host.sh

docker compose \
  --env-file deploy/self-host/.env.hosting \
  -f deploy/self-host/docker-compose.hosting.yml \
  up -d --build

Default endpoints:

  • Observatory: http://localhost
  • API health: http://localhost:8080/api/health
  • NATS: nats://localhost:4222

This is the right mode for:

  • local Docker or OrbStack testing on a laptop or Mac mini
  • a home server used only from the same machine
  • a home server reached over LAN, Tailscale, or another VPN

For LAN or VPN access, keep the same Compose file and set:

bash
COLEO_BIND_HOST=0.0.0.0
COLEO_PUBLIC_ORIGIN=http://<your-private-hostname-or-tailscale-name>

Examples:

  • COLEO_PUBLIC_ORIGIN=http://macmini.local
  • COLEO_PUBLIC_ORIGIN=http://macmini.tailnet-name.ts.net

Public internet exposure ​

Only add the edge overlay when you want public DNS hostnames, TLS termination, and browser auth in front of the Observatory/API.

bash
docker compose \
  --env-file deploy/self-host/.env.hosting \
  -f deploy/self-host/docker-compose.hosting.yml \
  -f deploy/self-host/docker-compose.hosting.edge.example.yml \
  up -d --build

Before using the edge overlay, set at least:

  • COLEO_DOMAIN
  • AUTH_DOMAIN
  • ACME_EMAIL
  • AUTH_ADMIN_PASSWORD_HASH

The edge overlay adds:

  • Traefik
  • Authelia
  • optional Tailscale sidecar integration

Most home-server users should use the base stack over Tailscale or another VPN before introducing the public edge overlay.

Hosted OpenCode Image Requirements ​

The Coleo Docker image is built for the hosted web UI/API path and includes:

  • Bun and Node/npm for Coleo, Vite, and JavaScript/TypeScript projects
  • Git, OpenSSH, curl/wget, jq, ripgrep, tmux, Python, and build tools for common repository work
  • the current opencode-ai CLI from npm, available as opencode
  • a production web UI build served by coleo web instead of the Vite dev server
  • a hosting entrypoint that can initialize .coleo, clone a target repository, and start the API, web UI, brain, and OpenCode arm agent

For OpenCode-only hosted arms, set these environment variables in deploy/self-host/.env.hosting:

bash
# Repository the arm agent should work in.
COLEO_GIT_REPO_URL=https://github.com/your-org/your-repo.git
COLEO_GIT_REF=main
COLEO_GIT_PULL_ON_START=1

# Coleo API auth and provider credentials.
COLEO_API_KEY=<generated-by-bootstrap-host>
OPENCODE_API_KEY=<your-opencode-key>

# Optional, for private GitHub clones or GitHub API access from arms.
GITHUB_TOKEN=<github-token>

The repository is cloned into /home/coleo/projects/app. The arm-agent service starts from that directory and advertises OpenCode capabilities over NATS, so arms created from the web UI can run headlessly through the opencode-api harness.

Bootstrap Behavior ​

./deploy/self-host/bin/bootstrap-host.sh is safe to rerun.

It will:

  • create deploy/self-host/.env.hosting if missing
  • fill missing local/private defaults
  • generate missing secrets
  • preserve existing COLEO_API_KEY and COLEO_BOOTSTRAP_TOKEN
  • render optional edge config templates if envsubst is available

Initialization ​

The hosting image does not run coleo init during image build. By default, the container entrypoint runs a non-interactive coleo init on first startup when /home/coleo/.coleo/config.toml is missing.

If you disable that behavior with COLEO_INIT_ON_START=0, initialize runtime state on the host where you want persistent Coleo data to live:

bash
docker compose \
  --env-file deploy/self-host/.env.hosting \
  -f deploy/self-host/docker-compose.hosting.yml \
  exec observatory coleo init --dir /home/coleo/.coleo --non-interactive

What Docker Gives You ​

The Docker path is best when you want:

  • a stable local or home-server service
  • one command to bring up the UI, API, brain, and NATS together
  • a clean path to later public exposure with Traefik and Authelia

If you prefer to run Coleo directly from your terminal instead, use the non-Docker path in Getting Started.