Agent Images

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, headless	Complex multi-tool tasks

Tier Dependency Map

Each tier implies a set of infrastructure dependencies resolved automatically by the Controller at dispatch time.

Tier	Service deps	Port deps
basic	--	--
codeready	navegador-redis	--
mesh	scuttlebot-irc	--
terminal	--	6080 (noVNC)
browser	--	6080 (noVNC)
full	scuttlebot-irc, navegador-redis	--
desktop	scuttlebot-irc, navegador-redis	6080 (noVNC)

Dockerfile Structure

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

docker/
├── agent-basic/claude/Dockerfile
├── agent-terminal/
│   ├── all/Dockerfile
│   ├── claude/Dockerfile
│   ├── codex/Dockerfile
│   └── gemini/Dockerfile
├── agent-browser/...
├── agent-desktop/
│   ├── debian/...
│   └── ubuntu/...
└── 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

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

Environment Variables

Agent containers receive these env vars at spawn time:

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
make agent-build TIER=terminal RUNTIME=claude

# Build all runtimes for a tier
make agent-build-all TIER=terminal

# Push to local registry (k3d)
make agent-push TIER=terminal RUNTIME=claude REGISTRY=localhost:5000

Or manually:

docker build -f docker/agent-terminal/claude/Dockerfile \
  -t kohakku-agent-terminal-claude:latest .

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 Image

# Quick test with agent-test image
make agent-test

# 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

Desktop Flavors

Flavor	Tag	Base	Notes
Ubuntu 24.04 LTS	ubuntu	ubuntu:24.04	Firefox + Chromium via PPAs, Go, Rust, gh CLI
Debian Bookworm	debian	debian:bookworm-slim	Firefox ESR + Chromium, Playwright included
OpenClaw	openclaw	ubuntu:24.04	Hardened Ubuntu for OpenClaw AI workloads

-all Runtime Activation

The -all images install all three CLIs but defer the choice to spawn time. The task request includes a cmd_override field; the Dispatcher passes it as the container entrypoint. A universal entrypoint script routes based on the AGENT_RUNTIME env var (claude / gemini / codex), falling back to per-CLI defaults if not set.