An image is the consistent base for a set of environments. It consists of a ledger of image versions.

There should be an image for each group of consistent environments.

Integrated Registry

Coder comes bundled with an integrated Docker registry. You can docker login <manager_host> to authenticate your local Docker toolchain with Coder. After you're authenticated, you can push and pull images like with any other registry.


An Image Version is a single deployment of an image.

Each image version is stored in the container registry that comes bundled with Coder.

Accepting Updates

The end developer is in charge of their environment. When they're outdated, a visual indicator appears in their editor so they're constantly nudged to update.

Read more about environments.

Tracking Updates

One can see the environments on each image version while listing or inspecting image versions. This helps the team understand divergence in real time, and allows teammates to nudge eachother to update.

Listing Image versions

Run ce image-versions list <image> to list all image versions, sorted by time.

Image Version States

An image version is either Active, or Inactive depending on whether any environments use it.

An image version can be Latest or Outdated depending on whether it is the most recent one for the image.

User Management

Give developers access to the image through the Dashboard or CLI. Simply navigate to the Images page in the dash, and press the + button on an image to add a new developer.

Users given the write role against the image may

  • Push new image versions
  • Edit image versions
  • Add new readers/writers to the image version

Base Images

Base Images are docker images that should be branched off of to create custom images for developer's to use in their environments.

The base images contain dependencies that environments needs to run, and general utilities and tooling to provide a more fully featured development environment.


There are a few requirements for a base image:

  • bash
  • curl
  • GLIBC version 2.17 or later

Extending Base Images

To add additional tooling and configuration, you can extend these base images using a Dockerfile and setting the FROM to point to the specific base image you want to extend. For example, if you wanted to extend the main ubuntu base image, your Dockerfile's FROM would look like the following:

FROM coderenvs/ubuntu:latest

After extending the base image, your custom image should be pushed up to the docker registry that your cemanager is connected to.

For instructions on how to register your image and new image version with the cemanager, see creating an image version.

Table of Contents