Install via Docker

What you'll accomplish: Run Hoziron as a container, mount your config, and verify the health endpoint.

1. Create a config file

# config.toml
[default_model]
provider = "anthropic"
model_id = "claude-sonnet-4-20250514"

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

2. Run the container

docker run -d --name hoziron -p 4200:4200 \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -v "$(pwd)/config.toml:/data/config.toml:ro" \
  ghcr.io/hozironos/hoziron:latest

Key points:

  • Config is mounted read-only (:ro) — only /data is writable
  • The container runs as UID 65532 (distroless nonroot)
  • Provider API keys are injected via environment variables

3. Verify health

curl http://localhost:4200/health

You should get a JSON response with "overall": "Healthy".

4. Create an agent via API

curl -X POST http://localhost:4200/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "triggers": [{"lifecycle": {}}]
  }'

Using Docker Compose

For a more complete setup with volumes and health checks:

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:

Connecting to local models (Ollama)

If you're using Ollama on the host machine:

docker run -d --name hoziron -p 4200:4200 \
  -v "$(pwd)/config.toml:/data/config.toml:ro" \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/hozironos/hoziron:latest

In your config.toml:

[default_model]
provider = "ollama"
model_id = "llama3.1:70b"

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

Start Ollama with OLLAMA_HOST=0.0.0.0 ollama serve so it's reachable from Docker's bridge network.

Next steps

You've got a running container. Now create your first agent.

Related: