Docker Compose Deployment

What you'll accomplish: Deploy Hoziron with Docker Compose including persistent volumes, health checks, and structured logging.

Compose file

services:
  hoziron:
    image: ghcr.io/hozironos/hoziron:latest
    ports:
      - "4200:4200"
    volumes:
      - ./config.toml:/data/config.toml:ro
      - hoziron-data:/data
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - HOZIRON_LOG=info
      - HOZIRON_LOG_FORMAT=json
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:4200/health"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  hoziron-data:

Key details

  • Config is read-only (:ro) — only /data is writable
  • UID 65532 — the container runs as distroless nonroot
  • Health checks — Docker monitors the /health endpoint
  • Persistent volume — hoziron-data preserves agent state and databases across restarts
  • JSON logging — recommended for container log collectors (Fluentd, Loki, CloudWatch)

Configuration

Create a config.toml alongside your docker-compose.yml:

[default_model]
provider = "anthropic"
model_id = "claude-sonnet-4-20250514"

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
enabled = true

[server]
listen = "0.0.0.0:4200"

[server.tls]
enabled = false

TLS is disabled because Docker networking handles internal traffic. If you need TLS at the container level, see TLS and networking.

Connecting to local models

If Ollama runs on the host:

services:
  hoziron:
    image: ghcr.io/hozironos/hoziron:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"
    # ...

And in config.toml:

[providers.ollama]
base_url = "http://host.docker.internal:11434"
enabled = true

Start Ollama with OLLAMA_HOST=0.0.0.0 ollama serve.

Volume permissions

If you encounter "Permission denied" errors:

# Ensure the volume is writable by UID 65532
docker run -v hoziron-data:/data --user 65532:65532 ...

Verify

docker compose up -d
docker compose ps     # Should show "healthy"
curl http://localhost:4200/health

Next steps

Related: