Writing Dockerfiles for Templates

Every Vibengine template is defined by a standard Dockerfile. If you have written a Dockerfile before, you already know most of what you need. This page covers the requirements and best practices specific to Vibengine.

Base Image Requirement

Your Dockerfile must start from a Debian or Ubuntu based image. The Vibengine sandbox agent depends on glibc and is incompatible with musl-based distributions like Alpine.

The recommended approach is to use the official Vibengine base image:

FROM vibengine/base:latest

This image includes the sandbox agent, common utilities, and is optimized for fast startup. You can also use any Debian or Ubuntu image, but the Vibengine agent will be injected automatically during the build.

Do not use Alpine, Distroless, or scratch-based images. Your sandbox will fail to start.

Basic Structure

A typical template Dockerfile follows this pattern:

FROM vibengine/base:latest

# Install system-level dependencies
RUN apt-get update && apt-get install -y \
    your-package-here \
    another-package \
    && rm -rf /var/lib/apt/lists/*

# Install language-specific packages
RUN pip3 install some-python-package

# Copy configuration files if needed
COPY config.json /home/user/.config/

# Set working directory
WORKDIR /home/user

Example: Python Data Science

A template pre-loaded with common data science libraries:

FROM vibengine/base:latest

RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-dev \
    libffi-dev \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install --no-cache-dir \
    numpy==1.26.4 \
    pandas==2.2.0 \
    matplotlib==3.8.2 \
    scikit-learn==1.4.0 \
    jupyter

WORKDIR /home/user

Example: Node.js Application

A template with Node.js and common tooling:

FROM vibengine/base:latest

# Install Node.js 20 LTS
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

# Install global packages
RUN npm install -g typescript tsx prettier eslint

WORKDIR /home/user

Example: Go Development

A template with the Go toolchain:

FROM vibengine/base:latest

ENV GOLANG_VERSION=1.22.0

RUN curl -fsSL "https://go.dev/dl/go${GOLANG_VERSION}.linux-amd64.tar.gz" \
    | tar -C /usr/local -xzf -

ENV PATH="/usr/local/go/bin:${PATH}"
ENV GOPATH="/home/user/go"
ENV PATH="${GOPATH}/bin:${PATH}"

RUN go install golang.org/x/tools/gopls@latest

WORKDIR /home/user

Best Practices

Minimize Layer Count

Combine related RUN commands with && to reduce image layers and total size:

# Good — single layer
RUN apt-get update && apt-get install -y \
    curl git wget \
    && rm -rf /var/lib/apt/lists/*

# Avoid — three separate layers
RUN apt-get update
RUN apt-get install -y curl git wget
RUN rm -rf /var/lib/apt/lists/*

Clean Up Package Caches

Always remove package manager caches after installing to keep the image small:

# APT cache cleanup
RUN apt-get update && apt-get install -y ... \
    && rm -rf /var/lib/apt/lists/*

# Pip cache cleanup
RUN pip3 install --no-cache-dir package1 package2

Pin Dependency Versions

Pin versions to ensure reproducible builds across time:

RUN pip3 install numpy==1.26.4 pandas==2.2.0

Do Not Override ENTRYPOINT

Vibengine uses a specific entrypoint to launch the sandbox agent. Overriding ENTRYPOINT or CMD in your Dockerfile will be ignored — the agent entrypoint takes precedence.

Setting ENTRYPOINT or CMD in your Dockerfile has no effect. The Vibengine agent manages process startup inside the sandbox.

Use WORKDIR for Default Directory

Set WORKDIR to control where commands execute by default when the sandbox starts:

WORKDIR /home/user/project

File Copying

You can include files alongside your Dockerfile and copy them into the template:

COPY setup.sh /home/user/setup.sh
COPY .bashrc /home/user/.bashrc

Place these files in the same directory as your Dockerfile and ve.toml. They will be included in the build context automatically.

Next Steps

Build templates — Learn how to build and push your Dockerfile
Template examples — Browse complete working examples

Dockerfile

On this page