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

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

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.

Runtime Comparison

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