Runtimes

Colima supports multiple container runtimes out of the box. This guide covers how to start and use each runtime.

Docker

Docker is the default runtime. It provides full compatibility with the Docker CLI and ecosystem.

Starting Docker Runtime 

colima start

Or explicitly specify the runtime:

colima start --runtime docker

Using Docker

Once started, you can use Docker commands directly:

# Run a container
docker run hello-world

# Run an interactive container
docker run -it alpine sh

# List running containers
docker ps

# List all containers
docker ps -a

# List images
docker images

Docker Compose

Docker Compose works out of the box:

# Start services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

Docker Context

Colima automatically creates and activates a Docker context. You can manage contexts with:

# List contexts
docker context ls

# Switch to Colima context
docker context use colima

# Switch to default context
docker context use default

Kubernetes

Colima can run a local Kubernetes cluster using k3s.

Starting Kubernetes 

colima start --kubernetes

With custom resources for larger workloads:

colima start --kubernetes --cpus 4 --memory 8

Using Kubernetes

Once started, kubectl is automatically configured:

# Check cluster status
kubectl cluster-info

# Run a pod
kubectl run caddy --image=caddy

# List pods
kubectl get pods

# List all resources
kubectl get all

# View pod logs
kubectl logs <pod-name>

Kubernetes Version

Specify a k3s version:

colima start --kubernetes --kubernetes-version v1.28.3+k3s1

Additional k3s Arguments

Pass additional arguments to k3s:

colima start --kubernetes --k3s-arg "--disable=traefik"

Managing Kubernetes

You can start, stop, or reset Kubernetes on a running Colima instance:

# Start Kubernetes
colima kubernetes start

# Stop Kubernetes
colima kubernetes stop

# Reset Kubernetes cluster
colima kubernetes reset

Containerd

Containerd is a lightweight container runtime. Colima includes a built-in nerdctl wrapper for a Docker-compatible CLI experience.

Starting Containerd Runtime 

colima start --runtime containerd

Using colima nerdctl

Use Colima’s built-in nerdctl command (no installation required):

# Run a container
colima nerdctl -- run hello-world

# Run an interactive container
colima nerdctl -- run -it alpine sh

# List running containers
colima nerdctl -- ps

# List images
colima nerdctl -- images

# Build an image
colima nerdctl -- build -t myapp .

Compose with nerdctl

nerdctl supports Docker Compose files:

# Start services
colima nerdctl -- compose up -d

# Stop services
colima nerdctl -- compose down

Installing nerdctl for Direct Use

If you prefer to use nerdctl directly without the colima nerdctl -- prefix, you can install it:

# Install nerdctl for the default profile
colima nerdctl install

# Install nerdctl for a custom profile
colima nerdctl install -p myprofile

After installation, you can use nerdctl directly:

nerdctl run hello-world
nerdctl ps
nerdctl images

Customizing Containerd Config

On first startup, Colima generates default config files at the standard user config locations:

File Location
Containerd config ~/.config/containerd/config.toml
BuildKit config ~/.config/buildkit/buildkitd.toml

These are shared across all Colima profiles. Edit the files and restart for changes to take effect:

$EDITOR ~/.config/containerd/config.toml
colima stop && colima start --runtime containerd

To use a different config for a specific profile, place the file at ~/.colima/<profile>/containerd/config.toml (or buildkitd.toml). Per-profile configs take priority over the central config.

Note: $XDG_CONFIG_HOME is respected for the central config location if set.

Incus

Incus is a modern container and virtual machine manager (fork of LXD). It supports both system containers and VMs.

Starting Incus Runtime 

colima start --runtime incus

Using Incus

Once started, you can use incus commands:

# Launch an Alpine container
incus launch images:alpine/edge mycontainer

# Launch an Ubuntu container
incus launch images:ubuntu/24.04 ubuntu

# List containers
incus list

# Execute command in container
incus exec mycontainer -- sh

# Stop a container
incus stop mycontainer

# Delete a container
incus delete mycontainer

Incus Virtual Machines

Incus can also run full virtual machines:

# Launch a VM
incus launch images:ubuntu/24.04 myvm --vm

# List VMs and containers
incus list

Note: Running Incus virtual machines requires nested virtualization. On Apple Silicon Macs, this feature is only available on M3 chips or newer.

Incus Profiles

Manage resource limits with profiles:

# List profiles
incus profile list

# Show default profile
incus profile show default

# Edit profile
incus profile edit default

Direct Host Access

As of v0.10.0, Incus instances are directly reachable from your macOS host via their IP addresses when network address is enabled:

# Start with network address enabled
colima start --runtime incus --network-address

# Launch a container
incus launch images:alpine/edge mycontainer

# Get the container's IP address
incus list

# Access the container directly from macOS
ping <container-ip>
ssh user@<container-ip>

This makes it easy to access services running inside Incus containers without port forwarding.

Switching Runtimes

To switch between runtimes, you need to stop and restart Colima:

# Stop current instance
colima stop

# Start with different runtime
colima start --runtime containerd

Or use different profiles for different runtimes:

# Docker profile
colima start docker

# Containerd profile
colima start containerd --runtime containerd

# Kubernetes profile
colima start k8s --kubernetes

# Incus profile
colima start incus --runtime incus

# List all profiles
colima list

Updating Runtimes

Colima can update the runtime components within the VM using the colima update command. This updates the runtime to the latest available version without recreating the VM.

# Update the runtime for the default profile
colima update

# Update the runtime for a specific profile
colima update myprofile

Note: The update command works for Docker, Kubernetes, and Incus runtimes. Containerd runtime updates are not currently supported.

Data Persistence

Soft Delete

Running colima delete without the --data flag performs a soft delete: the VM is removed but the runtime data is preserved on disk. On the next colima start, data is automatically restored.

Runtime Auto-restore on next start
Docker ✅ Yes
Containerd ✅ Yes
Kubernetes ❌ Not supported
Incus ⚠️ Requires recovery steps

Note: Hard delete (colima delete --data) permanently removes all data and cannot be recovered.

Note: Data recovery only applies to the same runtime. Colima will refuse to restore the data when started with a different runtime.

Recovering Incus Data After Soft Delete

When starting an Incus instance after a soft delete, Colima detects existing data and prompts for recovery. Colima will run incus admin recover interactively to restore the storage pool and containers.

Step-by-step recovery:

  1. Respond y when asked whether to recover existing storage pool(s).

  2. Colima prints the paths of all found storage pools and begins the incus admin recover process.

  3. Respond yes when asked “Would you like to recover another storage pool?”

  4. Enter default when asked for the name of the storage pool.

  5. Enter zfs when asked for the storage backend.

  6. Enter the exact path printed by Colima when asked for the source of the storage pool (e.g. /var/lib/incus/disks/default.img).

  7. Press Enter to leave additional configuration properties empty.

  8. Respond no when asked again if you would like to recover another storage pool (unless you have additional manually-created pools — repeat steps 3–7 for each).

  9. Press Enter to accept the default (yes) when asked to continue scanning for lost volumes.

  10. Respond yes when asked whether to recover the listed containers.

If you have multiple storage pools (created manually), Colima prints the paths for all of them. Repeat the pool-entry steps for each pool before answering no to finish.

Example recovery session:

existing Incus data found, would you like to recover the storage pool(s)? [y/N] y
INFO[0030] Running 'incus admin recover' ...             context=incus
INFO[0030] Found 1 storage pool source(s):               context=incus
INFO[0030]   /var/lib/incus/disks/default.img            context=incus

This server currently has the following storage pools:
Would you like to recover another storage pool? (yes/no) [default=no]: yes
Name of the storage pool: default
Name of the storage backend (lvm, dir, truenas, zfs, btrfs): zfs
Source of the storage pool (block device, volume group, dataset, path, ... as applicable): /var/lib/incus/disks/default.img
Additional storage pool configuration property (KEY=VALUE, empty when done):
Would you like to recover another storage pool? (yes/no) [default=no]: no
The recovery process will be scanning the following storage pools:
 - NEW: "default" (backend="zfs", source="/var/lib/incus/disks/default.img")
Would you like to continue with scanning for lost volumes? (yes/no) [default=yes]:
Scanning for unknown volumes...
The following unknown storage pools have been found:
 - Storage pool "default" of type "zfs"
The following unknown volumes have been found:
 - Container "ubuntu" on pool "default" in project "default" (includes 0 snapshots)
Would you like those to be recovered? (yes/no) [default=no]: yes
Starting recovery...
INFO[0111] starting ...                                  context=incus
INFO[0112] done

After the recovery process completes, the existing containers and storage pool are fully restored.

Runtime Comparison

Feature Docker Containerd Kubernetes Incus
OCI Containers ✅ ✅ ✅ ✅
System Containers ❌ ❌ ❌ ✅
Virtual Machines ❌ ❌ ❌ ✅
Compose Support ✅ ✅ (nerdctl) ❌ ❌
Orchestration ✅ (Swarm) ❌ ✅ ❌
CLI Tool docker nerdctl kubectl incus