hanzo-stack

Hanzo Stack provides the complete integrated development environment for running all Hanzo services locally.

Hanzo Stack - Full Integrated Development Environment

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-llm-gateway.md, hanzo/hanzo-cloud.md, hanzo/hanzo-database.md

Overview

Hanzo Stack provides the complete integrated development environment for running all Hanzo services locally. One command to start everything: LLM Gateway, Chat, Console, Cloud, IAM, KMS, PostgreSQL, Redis, MongoDB, MinIO.

NOTE: The stack uses three compose files (production, development, core) and git submodules for all services, allowing each service to track its own repo while being orchestrated together.

Why Hanzo Stack?

One-command setup: make dev starts everything
Three compose profiles: Production, development (hot-reload), core (minimal)
Git submodules: Each service tracks its own repo
Full ecosystem: All Hanzo services running locally
Hot-reload: Development mode with file watching
Consistent: Same compose config for all developers
Offline-capable: Local models via LLM Gateway + Ollama

When to use

Local development across multiple Hanzo services
Testing integrations between Hanzo components
Full-stack AI application development
Onboarding new team members
Reproducing production issues locally

Hard requirements

Docker with compose v2
16GB+ RAM (recommended for full stack)
make (standard on macOS/Linux)

Quick reference

| Item | Value | |------|-------| | Repo | github.com/hanzoai (experiments/stack directory) | | Setup | make setup | | Start prod | make up | | Start dev | make dev | | Start core | make core | | Status | make status | | Stop | make down | | Logs | make logs |

Three Compose Files

| File | Purpose | Services | |------|---------|----------| | compose.yml | Production — optimized, no hot-reload | All services, release images | | compose.dev.yml | Development — hot-reload, source mounts | All services, volume mounts | | compose.core.yml | Core — minimal set for quick start | LLM Gateway, Chat, PostgreSQL, Redis |

# Production mode
make up # Uses compose.yml

# Development mode (hot-reload)
make dev # Uses compose.yml + compose.dev.yml override

# Core only (minimal, fast startup)
make core # Uses compose.core.yml

Git Submodules

Each service is a git submodule tracking its own repo:

experiments/stack/
├── services/
│ ├── llm/ → github.com/hanzoai/llm (LLM Gateway)
│ ├── chat/ → github.com/hanzoai/chat (Chat UI)
│ ├── console/ → github.com/hanzoai/console (Console)
│ ├── cloud/ → github.com/hanzoai/cloud (Cloud Dashboard)
│ ├── search/ → github.com/hanzoai/search (Search)
│ ├── commerce/ → github.com/hanzoai/commerce (Commerce API)
│ └── ...
├── compose.yml # Production compose
├── compose.dev.yml # Development overrides
├── compose.core.yml # Minimal core services
├── .env.example # Environment template
├── Makefile # All commands
└── README.md

# Initialize submodules
git submodule update --init --recursive

# Update all submodules to latest
git submodule update --remote

# Update specific service
cd services/chat && git pull origin main

Service Ports

| Service | Port | URL | Description | |---------|------|-----|-------------| | Search UI | 3000 | http://localhost:3000 | AI-powered search | | Chat UI | 3081 | http://localhost:3081 | Hanzo Chat | | LLM Gateway | 4000 | http://localhost:4000 | Unified LLM proxy | | Payment API | 4242 | http://localhost:4242 | Commerce API | | Admin UI | 5173 | http://localhost:5173 | Admin dashboard | | Core API | 8000 | http://localhost:8000 | Main API server | | PostgreSQL | 5432 | postgresql://localhost:5432 | Primary database | | Redis | 6379 | redis://localhost:6379 | Cache/queues | | MongoDB | 27017 | mongodb://localhost:27017 | Document storage | | MinIO | 9000 | http://localhost:9000 | S3-compatible storage | | Prometheus | 9090 | http://localhost:9090 | Metrics collection |

One-file quickstart

# Clone and setup
git clone --recurse-submodules https://github.com/hanzoai/experiments.git
cd experiments/stack

# Configure environment
make setup # Creates .env from .env.example, prompts for API keys

# Start all services (pick one)
make core # Minimal: LLM + Chat + Postgres + Redis
make dev # Full stack with hot-reload
make up # Full stack, production mode

# Verify
make status # Check all services are healthy
curl http://localhost:4000/v1/models # List available models
curl http://localhost:3081 # Open Chat UI

Makefile Commands

make setup # Initial setup (env, pull images, init submodules)
make up # Start all services (production mode)
make dev # Start with hot-reload (development)
make core # Start minimal core services only
make down # Stop all services
make restart # Restart all services
make status # Show service status and health
make logs # Stream all logs
make logs-llm # Stream LLM Gateway logs only
make logs-chat # Stream Chat logs only
make clean # Remove volumes and data
make pull # Pull latest images
make build # Build local images
make test # Run integration tests
make reset # Full reset (clean + setup)
make update # Update all git submodules

Environment Configuration

# .env (created by make setup)

# Required: At least one LLM provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
HANZO_API_KEY=hanzo-...

# Optional: Local models
OLLAMA_URL=http://host.docker.internal:11434

# Database
DATABASE_URL=postgresql://hanzo:hanzo@postgres:5432/hanzo
REDIS_URL=redis://redis:6379

# IAM
IAM_ENDPOINT=https://hanzo.id
IAM_CLIENT_ID=app-hanzo
IAM_CLIENT_SECRET=secret

# KMS
KMS_ENDPOINT=https://kms.hanzo.ai
KMS_CLIENT_ID=...
KMS_CLIENT_SECRET=...

Compose Architecture

┌─────────────────────────────────────────┐
│ compose.yml + compose.dev.yml │
├─────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────┐ │
│ │ Chat UI │ │ Search │ │ Admin │ │
│ │ :3081 │ │ :3000 │ │ :5173 │ │
│ └────┬─────┘ └────┬─────┘ └───┬───┘ │
│ │ │ │ │
│ ┌────┴──────────────┴────────────┴───┐ │
│ │ LLM Gateway :4000 │ │
│ └────────────────┬───────────────────┘ │
│ │ │
│ ┌────────────────┴───────────────────┐ │
│ │ Core API :8000 │ │
│ └──┬─────────┬──────────┬───────────┘ │
│ │ │ │ │
│ ┌──┴───┐ ┌──┴───┐ ┌───┴────┐ ┌─────┐│
│ │Postgres│ │Redis │ │MongoDB │ │MinIO││
│ │ :5432 │ │:6379 │ │ :27017 │ │:9000││
│ └───────┘ └──────┘ └────────┘ └─────┘│
└─────────────────────────────────────────┘

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Port conflict | Service already running | lsof -i :PORT && kill PID | | OOM | Too many services | Use make core for minimal stack | | Slow start | Image pull | make pull beforehand | | DB connection fail | Postgres not ready | Wait or make restart | | Chat not loading | Missing OPENAI_API_KEY | Add at least one LLM key to .env | | Submodule empty | Not initialized | git submodule update --init --recursive |

# Debug specific service
docker compose logs -f llm-gateway
docker compose exec postgres psql -U hanzo

# Reset everything
make clean && make setup && make dev

# Port conflicts
lsof -i :4000 # Find what's using the port

Related Skills

hanzo/hanzo-llm-gateway.md - LLM proxy (port 4000)
hanzo/hanzo-chat.md - Chat UI (port 3081)
hanzo/hanzo-database.md - PostgreSQL/Redis setup
hanzo/hanzo-o11y.md - Monitoring (Prometheus port 9090)
hanzo/hanzo-universe.md - Production K8s (vs local stack)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: stack, development, local, docker, compose, submodules Prerequisites: Docker, make, 16GB+ RAM