Custom Containerfile

The default ClusterCode DevBox image covers general development. For specialized needs, build your own.

Note

Custom images (BYOI) require a Pro or Enterprise plan.

Tip

Prefer to capture a DevBox you’ve already set up by hand? See Build an Image from a DevBox.

Base image

Start from the ClusterCode base image to get all default tools:

FROM localhost/claude-code-terminal:latest

# Add your customizations
RUN npm install -g typescript @angular/cli

Example: Python data science environment

FROM localhost/claude-code-terminal:latest

RUN apt-get update && apt-get install -y python3 python3-pip python3-venv \
    && pip3 install pandas numpy scikit-learn jupyter \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

Example: Rust development

FROM localhost/claude-code-terminal:latest

RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
    && . $HOME/.cargo/env \
    && rustup component add clippy rustfmt

Building

For a custom image to appear in the launch picker it has to be a managed image — one ClusterCode tags with io.clustercode.managed. The orchestrator hides unmanaged images by default, so building through ClusterCode is the path that just works. Trigger a build from the orchestrator dashboard or Nucleus:

“Build my-custom-image from ./Containerfile”

This builds on your worker and stamps the managed label automatically, so the image shows up in the runtime picker.

Caution

A bare podman build on the worker host also works, but the resulting image is unmanaged and won’t appear in the launch picker:

podman build -t localhost/my-custom-image:latest -f Containerfile .

To make a hand-built image selectable, either build it through ClusterCode (above) or add the managed label yourself in the Containerfile:

LABEL io.clustercode.managed=true

Extra instructions in the browser

You don’t have to hand-write a whole Containerfile to make a small change. On the Build Image page, an Advanced section (Linux images, Pro plan and above) has an Extra Instructions field: a Monaco editor with Dockerfile syntax highlighting. What you type there is appended to the generated Containerfile as its own # === Extra instructions === block, placed after ClusterCode’s own finalize/cleanup step — the build then resets back to the non-root developer user, so anything your instructions left as root doesn’t leak into the running DevBox.

Because your instructions run after the base image and its capabilities are already assembled, FROM, ENTRYPOINT and CMD directives aren’t allowed here — the build rejects the field if it finds one. Use it for the kind of one-off tweak that doesn’t justify a whole custom Containerfile: an extra RUN apt-get install, an environment variable, a config file written with RUN echo.

Using your image

A custom image lives on the worker that built it, so the launch has to land on that worker. Open the launch flow, open the target picker, select that worker, then pick your image from the runtime list — the same worker-pinning flow as Launch from your golden image.