Configuration

Colima can be configured using command-line flags or a YAML configuration file.

Configuration File

Edit the configuration file interactively:

colima start --edit

This opens the configuration in your default editor. Specify a different editor with:

colima start --edit --editor code

Config file locations:

~/.colima/default/colima.yaml (default profile)
~/.colima/<profile>/colima.yaml (named profiles)

VM Resources

CPU, Memory, and Disk

# Number of CPUs
cpu: 4

# Memory in GiB
memory: 8

# Disk size in GiB (can only be increased after creation)
disk: 100

# Root filesystem disk size in GiB
rootDisk: 20

Or via command line:

colima start --cpus 4 --memory 8 --disk 100

Default values:

CPU: 2 cores
Memory: 2 GiB
Disk: 100 GiB

VM Configuration

Architecture

Set the VM architecture (immutable after creation):

# Options: x86_64, aarch64, host
arch: host

Run x86_64 containers on Apple Silicon:

colima start --arch x86_64

VM Type

Choose the virtualization technology (immutable after creation):

# Options: qemu, vz, krunkit
# vz requires macOS 13+
vmType: qemu

QEMU (default): Works on all platforms.

VZ Framework (macOS 13+): Apple’s Virtualization framework with better performance:

colima start --vm-type vz

VZ framework benefits:

Better performance
Rosetta 2 support for x86_64 emulation
VirtioFS support for faster file mounts

CPU Type

Specify CPU type for QEMU (supports instruction set extensions):

cpuType: host

Rosetta

Enable Rosetta for amd64 emulation on Apple Silicon (requires VZ):

rosetta: true

colima start --vm-type vz --vz-rosetta

Nested Virtualization

Enable nested virtualization on M3+ Macs (requires VZ):

nestedVirtualization: true

Hostname

Set a custom VM hostname:

hostname: my-colima

Default: colima or colima-<profile_name>

Runtime Configuration

Container Runtime

Choose the container runtime (immutable after creation):

# Options: docker, containerd, incus
runtime: docker

Kubernetes

Enable and configure Kubernetes:

kubernetes:
  # Enable Kubernetes
  enabled: true

  # k3s version (default: latest stable)
  version: v1.28.3+k3s1

  # Additional k3s arguments
  k3sArgs:
    - --disable=traefik

  # Kubernetes API port (0 = random)
  port: 6443

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

Docker Daemon Configuration

Configure Docker daemon settings (maps to daemon.json):

docker:
  # Insecure registries
  insecure-registries:
    - myregistry.local:5000

  # Registry mirrors
  registry-mirrors:
    - https://mirror.gcr.io

  # Other daemon options
  features:
    buildkit: true

Network Configuration

Network Address

Assign a reachable IP address to the VM (macOS only):

network:
  address: true

colima start --network-address

Note: Requires root privilege and increases startup time.

Network Mode

Set the network mode (macOS only):

network:
  # Options: shared, bridged
  mode: shared

  # Interface for bridged mode
  interface: en0

DNS Configuration

Set custom DNS resolvers:

network:
  dns:
    - 8.8.8.8
    - 1.1.1.1

colima start --dns 8.8.8.8 --dns 1.1.1.1

DNS Host Mappings

Map hostnames to custom targets:

network:
  dnsHosts:
    myapp.local: 192.168.1.100
    api.local: host.docker.internal

Gateway Address

Custom gateway address (last octet must be 2):

network:
  gatewayAddress: 192.168.5.2

Host Addresses

Replicate host IP addresses for port forwarding:

network:
  hostAddresses: true

Port Forwarding

Ports are automatically forwarded from containers to the host:

docker run -p 8080:80 caddy
# Access at http://localhost:8080

Configure the port forwarder:

# Options: ssh, grpc
portForwarder: ssh

Volume Mounts

Mount Type

Choose the volume mount driver (immutable after creation):

# Options: sshfs, 9p, virtiofs
mountType: sshfs

Mount type recommendations:

sshfs (default): Works everywhere, good compatibility
9p: Better performance than sshfs
virtiofs: Best performance (requires VZ on macOS 13+)

colima start --vm-type vz --mount-type virtiofs

Mount Configuration

Configure volume mounts:

mounts:
  # Home directory (default, writable)
  - location: ~
    writable: true

  # Additional mount (read-only)
  - location: /data
    writable: false

  # Project directory
  - location: ~/projects
    writable: true

Mount Inotify

Propagate inotify file events to VM (experimental):

mountInotify: true

colima start --mount-inotify

SSH Configuration

SSH Agent Forwarding

Forward host SSH agent to the VM:

forwardAgent: true

colima start --ssh-agent

SSH Config

Auto-update ~/.ssh/config with VM connection details:

sshConfig: true

SSH Port

Set a specific SSH port (0 = random):

sshPort: 0

Provisioning

Run scripts on VM startup (idempotent):

provision:
  - mode: system
    script: |
      apt-get update
      apt-get install -y htop

  - mode: user
    script: |
      echo "Hello from user script"

Modes:

system: Runs as root
user: Runs as the default user

Environment Variables

Set environment variables in the VM:

env:
  HTTP_PROXY: http://proxy.example.com:8080
  HTTPS_PROXY: http://proxy.example.com:8080
  NO_PROXY: localhost,127.0.0.1

Auto Activation

Automatically set as active Docker/Kubernetes context on startup:

autoActivate: true

Profiles

Run multiple Colima instances with different configurations:

# Create a development profile
colima start dev --cpus 4 --memory 8

# Create a Kubernetes profile
colima start k8s --kubernetes

# Create a containerd profile
colima start containerd --runtime containerd

# List all profiles
colima list

# Stop a specific profile
colima stop dev

# Delete a profile
colima delete dev

Each profile has its own configuration file at ~/.colima/<profile>/colima.yaml.

Immutable Settings

Some settings cannot be changed after the VM is created:

arch (architecture)
runtime (container runtime)
vmType (VM type)
mountType (volume mount driver)

To change these, delete and recreate the instance:

colima delete
colima start --runtime containerd --vm-type vz

Example Configurations

Development Machine

cpu: 4
memory: 8
disk: 100
vmType: vz
mountType: virtiofs
forwardAgent: true

docker:
  features:
    buildkit: true

CI/CD Environment

cpu: 2
memory: 4
disk: 50
runtime: docker

env:
  CI: true

Kubernetes Development

cpu: 4
memory: 8
disk: 100

kubernetes:
  enabled: true
  version: v1.28.3+k3s1
  k3sArgs:
    - --disable=traefik