Dockerfile Requirements

The container image used by Cloche workflows must meet the following requirements:

Required Components

Component Location Purpose
cloche-agent /usr/local/bin/cloche-agent In-container orchestrator that receives step instructions from the daemon over gRPC.
clo /usr/local/bin/clo Lightweight KV store CLI for reading and writing run data from inside the container.
git On $PATH Required for result extraction (the daemon uses git worktrees to extract changes).
agent user System user Cloche wraps commands with chown + su agent. Steps run as this unprivileged user.
/workspace Working directory The project is copied here at container start via docker cp.

Base Image

The cloche-base:latest image (built by make docker-build) includes cloche-agent, clo, git, and the agent user already configured. Use it as your base:

FROM cloche-base:latest
USER root

# Install your project's build dependencies
RUN apt-get update \
    && apt-get install -y --no-install-recommends nodejs npm python3 \
    && rm -rf /var/lib/apt/lists/*

# Install the agent binary
RUN npm install -g @anthropic-ai/claude-code

# Add project-specific build tools
# RUN pip install -r requirements.txt

USER agent

Guidelines

  • Switch to root for installs, back to agent at the end. The agent user does not have sudo access. Package installation requires USER root. Always end with USER agent so steps run unprivileged.

  • Do not override the entrypoint. The base image’s entrypoint handles credential injection (chown -R agent:agent on auth files) and sets up the container environment. If you need to run setup commands, use RUN in the Dockerfile instead.

  • Bake dependencies into the image. Install all build tools, language runtimes, and project dependencies at build time. This avoids network downloads at runtime (which may be blocked if you use network restrictions) and makes container startup faster.

  • Do not bake secrets into the image. API keys, tokens, and credentials should be passed at runtime via environment variables (CLOCHE_EXTRA_ENV, ANTHROPIC_API_KEY), not embedded in the Dockerfile. See the Safety Guide for details.

  • Keep the image small where practical. Use --no-install-recommends with apt, clean up caches, and combine RUN layers. Large images slow down the copy step at container start.