Prerequisites¶

hemlock-lab runs as a Docker Compose stack. This page covers everything you need before running docker compose up.

Host Machine¶

Requirement	Minimum
OS	macOS, Linux, or Windows (WSL2)
Free RAM	8 GB
Free disk	20 GB (Docker images + models)
CPU cores	4+ recommended

Docker¶

Docker Desktop (macOS/Windows) or Docker Engine (Linux) with Compose v2:

# Verify Docker is installed
docker --version        # 24.0+ recommended
docker compose version  # v2.20+ required

Docker Desktop

On macOS, allocate at least 8 GB RAM and 4 CPUs in Docker Desktop → Settings → Resources.

Ollama¶

Ollama runs on the host (not in Docker). Containers reach it via host.docker.internal:11434.

# Install Ollama (macOS)
brew install ollama

# Or download from https://ollama.com

# Start Ollama
ollama serve

# Pull the required models
ollama pull smollm2:135m       # LLM inference
ollama pull nomic-embed-text   # Embedding model
ollama pull nomic-embed-text   # Embeddings

Verify Ollama is running:

curl http://localhost:11434/api/tags | jq '.models[].name'

Ollama must be running before starting the stack

Pipeline containers connect to Ollama at startup. If Ollama is unreachable, health checks will fail.

Software¶

Tool	Purpose
`docker`	Container runtime
`docker compose`	Service orchestration
`ollama`	LLM inference on host
`curl`	Health checks and API testing
`jq`	JSON output formatting (optional)
`git`	Repository management

Optional: hemlock Binary¶

The harness container includes hemlock, but you can also install it locally for corpus generation:

# Build from source
go install github.com/professor-moody/hemlock/cmd/hemlock@latest

# Or download a release
curl -fsSL -o hemlock.tar.gz \
  https://github.com/professor-moody/hemlock/releases/latest/download/hemlock-v0.7.0-linux-amd64.tar.gz
tar -xzf hemlock.tar.gz
sudo install -m 755 hemlock /usr/local/bin/hemlock

Next Steps¶

Once all prerequisites are met:

Installation — Clone the repo and start the stack
Quick Start — Run your first test suite

Legacy: Proxmox Deployment

The original hemlock-lab ran on a single Proxmox VM (Ubuntu 24.04, VMID 260, 172.16.50.50) with systemd-managed services. The Proxmox deployment scripts are still available in lab-scripts/ for environments that require bare-metal installation. See lab-scripts/lib/inventory.sh for the VM configuration.