Skip to main content
The hud build command builds your Docker image, analyzes its MCP server, and writes a reproducible hud.lock.yaml.

​
Usage

hud build [DIRECTORY] [OPTIONS]

​
Arguments

​
directory
string
default:"."
Environment directory containing Dockerfile and pyproject.toml

​
Options

​
--tag
string
Docker image tag to use. Defaults to [tool.hud.image] or {dir}:dev.
​
--no-cache
boolean
default:"false"
Build without using Docker cache
​
--verbose
boolean
default:"false"
Show detailed build output. Short: -v
​
--platform
string
default:"linux/amd64"
Target platform for Docker build. Defaults to linux/amd64 if unspecified.

​
What It Does

1

Build Docker Image

Runs docker build (twice): a temporary build for analysis, then a labeled build for the final image and version tags.
2

Analyze Environment

Runs the container via MCP to measure initialize time and list tools (count and input schemas).
3

Generate Lock File

Writes hud.lock.yaml with:
  • version: lock format version
  • image: {tag}@sha256:<id> after final build
  • build: generatedAt, hudVersion, directory, internal version (semver, auto‑incremented), sourceHash, optional sourceFiles
  • environment: initializeMs, toolCount, and optional variables with provided, required, optional
  • tools: name, description, inputSchema (for RL/evals tooling)
4

Retag & Label

Adds labels (org.hud.*) and tags the image with both the chosen tag and the internal version.

​
Examples

# Basic build (auto tag)
hud build

# Custom tag
hud build . --tag v1.2.0

# Clean build with logs
hud build . --no-cache --verbose

# Force cross‑platform (useful on Apple Silicon)
hud build . --platform linux/amd64

​
Image Naming

If --tag is not provided:
  1. Read [tool.hud.image] from pyproject.toml
  2. Otherwise use {directory-name}:dev

​
Environment Variables

Pass runtime environment variables during analysis with -e/--env flags: 
hud build . -e API_KEY=secret -e DEBUG=true
They’re recorded in the lock file as placeholders under environment.variables.provided; missing required variables are listed in environment.variables.required.

​
Lock File

Minimal structure you’ll see: 
version: "1.2"
image: "my-env:0.1.0@sha256:..."
build:
  generatedAt: "2025-01-01T12:00:00Z"
  hudVersion: "0.x.y"
  directory: "my-env"
  version: "0.1.0"
  sourceHash: "..."
  baseImage: "python:3.11-slim"
  platform: "linux/amd64"
environment:
  initializeMs: 450
  toolCount: 3
  runtime:
    python: "3.11.6"
    cuda: null
    cudnn: null
    pytorch: null
  variables:
    provided: { API_KEY: "${API_KEY}" }
    required: ["OTHER_KEY"]
tools:
  - name: setup
    description: Initialize environment
    inputSchema: { type: object }
    internalTools: ["board", "seed"]

​
Next Steps

# Hot‑reload development
hud dev

# Run the built image locally (stdio)
hud run my-env:dev --local

# Push to registry
hud push

​
See Also