colima

name	colima
description	Use when Docker commands fail with "Cannot connect to Docker daemon", when starting/stopping container environments on macOS, when managing Docker contexts or profiles, or when running incus (system containers / VMs with nested virtualization) on macOS - provides Colima lifecycle management, profile handling, SSH commands, and troubleshooting

Colima

Overview

Colima provides container and VM runtimes (Docker, Containerd, Incus) on macOS with minimal setup. It runs a Linux VM and exposes the chosen runtime to the host.

Use this skill when:

• Docker commands fail ("Cannot connect to Docker daemon")
• Starting/stopping container runtime on macOS
• Managing multiple Docker profiles/contexts
• Troubleshooting container environment issues
• Need SSH agent forwarding for Docker builds
• Running incus on macOS (system containers or VMs with nested virtualization)

Not for: Docker Compose or Kubernetes clusters.

Quick Reference

Operation	Command
Start	colima start or colima start <profile>
Start with SSH agent	colima start <profile> -s
Stop	colima stop or colima stop --force
Status	colima status -p <profile>
List profiles	colima list
SSH into VM	colima ssh or colima ssh -- <cmd>
SSH with chained commands	colima ssh -- bash -c "cmd1 && cmd2"
Get socket path	colima status -p <profile> --json | jq -r .docker_socket

Docker Context Basics

Colima creates Docker contexts per profile:

• Profile default → context colima
• Profile work → context colima-work

# Switch context (global - affects all terminals)
docker context use colima-work

# Override per-session
export DOCKER_CONTEXT=colima-work

# Override per-command
docker --context colima-work ps

For details, see references/docker-contexts.md.

Common Issues

Docker daemon not connecting?

1. colima status - is it running?
2. docker context list - right context selected?
3. See references/troubleshooting.md for more

Need more VM resources?

colima stop && colima start --cpu 4 --memory 8

"Broken" status after restart?

colima stop --force && colima start

References

• references/ssh-commands.md - SSH command syntax, chaining, escaping
• references/docker-contexts.md - Context switching, DOCKER_HOST, socket paths
• references/profile-management.md - Creating, configuring, deleting profiles
• references/troubleshooting.md - Common issues and solutions
• references/common-options.md - Flags, VM types, resource configuration
• references/incus-runtime.md - Running incus (containers + VMs with nested virt) on Apple Silicon

Upstream Documentation

Local copies of official Colima docs (from github.com/abiosoft/colima):

• references/colima-upstream/README.md - Official README with features and usage
• references/colima-upstream/FAQ.md - Official FAQ and troubleshooting
• references/colima-upstream/INSTALL.md - Installation options