This guide explains how to build custom executor images for KubeOpenCode.

KubeOpenCode uses a two-container pattern for executing AI-powered tasks:

1. OpenCode Image (Init Container): Contains the OpenCode CLI, copies it to a shared volume
2. Executor Image (Worker Container): User's development environment that uses the OpenCode tool

This design separates the AI tool (OpenCode) from the execution environment, allowing users to bring their own toolsets while using a single, maintained AI agent.

┌─────────────────────────────────────────────────────────────┐
│                        Job Pod                               │
├─────────────────────────────────────────────────────────────┤
│  Init Container: opencode-init                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Image: kubeopencode-agent-opencode                   │  │
│  │  - Contains OpenCode CLI (AI agent)            │  │
│  │  - Copies opencode binary to /tools volume            │  │
│  └───────────────────────────────────────────────────────┘  │
│                           │                                  │
│                           ▼ shared volume (/tools)           │
│                                                              │
│  Main Container: worker                                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Executor Images:                                     │  │
│  │  ├── devbox        (full dev environment)             │  │
│  │  └── user-custom   (your own toolset)                 │  │
│  │                                                       │  │
│  │  Runs: /tools/opencode run "$(cat task.md)"           │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

The universal devbox image (kubeopencode-agent-devbox) provides a comprehensive development environment:

• zsh as default shell
• OpenShift compatible: Works with arbitrary UIDs (uses /tmp as HOME)

• Docker or Podman installed
• (Optional) Docker buildx for multi-arch builds

From the agents/ directory:

# Build OpenCode image (init container)
make AGENT=opencode build

# Build devbox image (executor)
make AGENT=devbox build

# Build attach image (Server mode)
make AGENT=attach build

# Multi-arch build and push
make AGENT=opencode buildx
make AGENT=devbox buildx
make AGENT=attach buildx

From the project root:

# Same commands via project Makefile
make agent-build AGENT=opencode
make agent-build AGENT=devbox
make agent-build AGENT=attach

Default: ghcr.io/kubeopencode/kubeopencode-agent-<name>:latest

Customize with variables:

Example:

make AGENT=devbox build IMG_REGISTRY=docker.io IMG_ORG=myorg VERSION=v1.0.0
# Builds: docker.io/myorg/kubeopencode-agent-devbox:v1.0.0

If the default devbox image doesn't meet your needs, you can create a custom executor image.

mkdir agents/my-executor

# My Custom Executor Image
FROM debian:bookworm-slim

# Install your tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    git \
    curl \
    your-custom-tools \
    && rm -rf /var/lib/apt/lists/*

# OpenShift compatibility: use /tmp as HOME for arbitrary UIDs
ENV HOME="/tmp"
ENV SHELL="/bin/bash"

# Create workspace directory
ARG WORKSPACE_DIR=/workspace
ENV WORKSPACE_DIR=${WORKSPACE_DIR}
RUN mkdir -p ${WORKSPACE_DIR} && chmod 777 ${WORKSPACE_DIR}

# Run as non-root
USER 1000:0

WORKDIR ${WORKSPACE_DIR}

CMD ["/bin/bash"]

# Build
make AGENT=my-executor build

# Test locally (simulating the init container pattern)
docker run --rm \
  -v /tmp/tools:/tools \
  -v /tmp/task.md:/workspace/task.md:ro \
  -e PATH="/tools:$PATH" \
  ghcr.io/kubeopencode/kubeopencode-agent-my-executor:latest \
  /tools/opencode run "$(cat /workspace/task.md)"

Every executor image should follow these conventions:

1. Work in /workspace directory: All context files are mounted here
2. Support /tools volume mount: OpenCode binary is injected here
3. Output to stdout/stderr: Results are captured as Job logs
4. Exit with appropriate code: 0 for success, non-zero for failure
5. OpenShift compatible: Use /tmp as HOME to support arbitrary UIDs

Configure via the Agent credentials field:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  # TBD: New fields for opencode image + executor image pattern
  credentials:
    - name: api-key
      secretRef:
        name: ai-credentials
        key: api-key
      env: ANTHROPIC_API_KEY
    - name: github-token
      secretRef:
        name: github-credentials
        key: token
      env: GITHUB_TOKEN

If the devbox image doesn't include a tool you need:

FROM ghcr.io/kubeopencode/kubeopencode-agent-devbox:latest

# Add additional tools
USER root
RUN apt-get update && apt-get install -y postgresql-client \
    && rm -rf /var/lib/apt/lists/*
USER 1000:0

If the tool is generally useful, consider adding it to devbox/Dockerfile and submitting a PR.

1. Run as non-root: Use UID 1000 or support arbitrary UIDs
2. Minimize packages: Only install what you need
3. Use specific versions: Pin tool versions for reproducibility
4. Credential handling: Never bake credentials into images; use Kubernetes secrets
5. OpenShift compatible: Use /tmp for HOME and cache directories

Check that:

• The workspace directory is writable
• Required environment variables (API keys) are set
• The /tools volume is properly mounted

If running on OpenShift or with arbitrary UIDs:

• Ensure HOME is set to /tmp
• Use chmod 777 for directories that need to be writable
• Don't rely on specific user IDs

If a tool is missing:

1. Check if it's in the devbox image
2. Create a custom executor with the tools you need
3. Consider contributing to the devbox image if generally useful

The larger size of devbox is a trade-off for having a comprehensive development environment similar to GitHub Actions runners. The attach image is intentionally minimal as it only needs to connect to an OpenCode server and stream output.