Agent Image Customization Guide¶

Image Naming¶

Agent images follow the convention: {registry}:{tier}-{runtime}-{tag}

Registry: AGENT_IMAGE_REGISTRY setting (default: localhost:5000/kohakku-agents)
Tier: basic, codeready, mesh, terminal, browser, desktop, full
Runtime: claude, codex, gemini, all
Tag: latest or git SHA

Example: ghcr.io/conflicthq/kohakku-agents:terminal-claude-latest

Tier Hierarchy¶

Tier	Capabilities	Use Case
basic	CLI only, no GUI	Classification, summarization, text processing
codeready	+ Navegador Redis, git tools	Code generation, repository work
mesh	+ Scuttlebot IRC relay	Multi-agent coordination
terminal	+ VNC/noVNC, terminal UI	Interactive terminal sessions
browser	+ Chromium, browser automation	Web scraping, UI testing
desktop	+ Full desktop (XFCE/OpenClaw)	Visual tasks, desktop automation
full	All of the above	Complex multi-tool tasks

Dockerfile Structure¶

Each tier lives in docker/agent-{tier}/{runtime}/Dockerfile:

docker/
├── agent-basic/claude/Dockerfile
├── agent-terminal/
│   ├── all/Dockerfile        # all runtimes combined
│   ├── claude/Dockerfile
│   ├── codex/Dockerfile
│   └── gemini/Dockerfile
├── agent-browser/...
├── agent-desktop/
│   ├── debian/...            # Debian + OpenClaw
│   └── ubuntu/...            # Ubuntu standard
└── shared/
    ├── entrypoint.sh         # Universal entrypoint
    ├── brief_download.py     # Brief download + skill loading
    └── bootstrap_prompt.py   # System prompt generation

Customizing an Image¶

Adding Tools¶

FROM kohakku-agent-terminal-claude:latest

# Add custom tools
RUN pip install custom-tool-package
COPY my-scripts/ /agent/scripts/

# Bake in a skill
COPY skills/my-skill/ /agent/skills/my-skill/package/

Adding a New Runtime¶

Create docker/agent-{tier}/{runtime}/Dockerfile
Install the runtime CLI
Add to the activate_runtime.sh detection logic
Add to the CI build matrix in .github/workflows/build-agents.yml

Environment Variables¶

Agent containers receive these env vars:

Variable	Source	Description
TASK_ID	Dispatcher	Task UUID
DISPATCH_AGENT_KEY	Dispatcher	Agent authentication key
DISPATCH_WEBHOOK_URL	Dispatcher	Dispatcher URL for check-in/check-back
BRIEF_URL	Controller	Presigned URL for brief download
BRIEF_KEY	Controller	S3 key for brief (fallback)
AGENT_RUNTIME	Image	Active runtime (claude/codex/gemini)
DISPATCH_DEPTH	Parent agent	Current recursion depth

Custom CMD¶

Set cmd_override on AgentDefinition to override the default entrypoint command:

agent_def = AgentDefinition.objects.create(
    name="Custom Agent",
    tier="terminal",
    runtime="claude",
    cmd_override="python /agent/custom_script.py",
)

Building Locally¶

# Build a specific tier/runtime
docker build -f docker/agent-terminal/claude/Dockerfile -t kohakku-agent-terminal-claude:latest .

# Build all via CI workflow
gh workflow run build-agents.yml -f tier=terminal

# Push to local registry (k3d)
docker tag kohakku-agent-terminal-claude:latest localhost:5000/kohakku-agents:terminal-claude-latest
docker push localhost:5000/kohakku-agents:terminal-claude-latest

Testing an Agent Image¶

# Quick test with agent-test image
docker run --rm -e TASK_ID=test-123 kohakku-agent-test:latest

# Interactive test
docker run -it --rm \
  -e TASK_ID=test-123 \
  -e DISPATCH_WEBHOOK_URL=http://host.docker.internal:8080 \
  kohakku-agent-terminal-claude:latest /bin/bash