Container Image

This guide explains how to build custom Docker images with pre-installed dependencies for your VM0 agents.

Overview

Custom images allow you to pre-install tools, libraries, and dependencies that your agent needs. This reduces startup time and ensures a consistent environment.

Building Images

Use vm0 image build to create a custom image from a Dockerfile:

vm0 image build -f Dockerfile -n my-image

Options

Dockerfile Restrictions

VM0 only supports FROM and RUN instructions in Dockerfiles. This is intentional - the purpose is to pre-install environment dependencies, not to configure application behavior.

# Allowed
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y nodejs npm

# NOT allowed (will fail validation)
COPY . /app
WORKDIR /app
ENV NODE_ENV=production

Naming Rules

Image names must follow these rules:

• 3-64 characters
• Letters, numbers, and hyphens only
• Must start and end with a letter or number
• Cannot start with vm0- (reserved for system images)

Image Reference Format

Images are referenced using a scope/name format with optional version tags.

Scope Resolution

Version Tags

Examples

# Your own image (uses your scope)
image: "my-image"

# Specific version of your image
image: "my-image:abc123def"

# Another user's image
image: "otheruser/their-image"

# System image
image: "vm0/claude-code"

Scope Setup

Before building images, you need to set up your scope:

vm0 scope set myusername

Your scope is a namespace for your images. After setting it, your images are referenced as myusername/image-name.

Implicit vs Explicit Scope

When you reference an image without a scope:

image: "my-image"

VM0 automatically resolves it to your scope:

# Internally resolved to:
image: "myusername/my-image"

When you reference an image with an explicit scope, it uses that scope directly:

# Uses exactly as specified
image: "otheruser/their-image"

Using Custom Images in vm0.yaml

Reference your custom image in the agent configuration:

version: "1.0"

agents:
  my-agent:
    provider: claude-code
    image: "my-image" # Uses your scope
    working_dir: /home/user/workspace

Or reference a system image explicitly:

version: "1.0"

agents:
  my-agent:
    image: "vm0/claude-code"
    working_dir: /home/user/workspace

Managing Images

List Images

View all your custom images:

vm0 image list

List Versions

View all versions of a specific image:

vm0 image versions my-image

Delete Images

Delete the latest version:

vm0 image delete my-image

Delete a specific version:

vm0 image delete my-image:abc123

Delete all versions:

vm0 image delete my-image --all

Skip confirmation prompt:

vm0 image delete my-image --force

System Images

VM0 provides built-in system images under the vm0 scope:

These are used automatically when you specify a provider without a custom image.