Hanzo Stack - Full Integrated Development Environment

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

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
HANZO_IAM_URL=https://hanzo.id
HANZO_IAM_CLIENT_ID=app-hanzo
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

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)

Hanzo Stack - Full Integrated Development Environment

On this page