| name | colima |
| description | Guide to using Colima — container runtimes (Docker, containerd, Kubernetes, Incus) on macOS and Linux via lightweight Lima VMs. Use this skill whenever Colima is (or should be) the container backend: installing Colima; `colima start/stop/status/delete/ssh`; picking or switching a runtime; the `Cannot connect to the Docker daemon at unix:///var/run/docker.sock` error; Docker contexts and socket location; registry mirrors / insecure registries; buildx; bind or volume mounts that show up empty in the container; disk space recovery/resize; reachable VM IP; GPU / AI model workloads; config files, profiles and `COLIMA_HOME`; or a Colima VM that won't start. ALSO use it for **writing scripts that drive Colima** — bootstrap, dev-env, deploy, or CI scripts that bring Colima up non-interactively — because the skill has the correct flags, profile-specific socket paths, idempotent `colima start` guards, and readiness/teardown patterns that hand-written scripts routinely get wrong (e.g. inventing a non-existent flag or hardcoding the wrong docker socket). Prefer this over generic Docker advice whenever Colima is the daemon. This skill is specifically about **Colima** — not Docker Desktop, minikube, Kind, K3d, Rancher Desktop, OrbStack, Podman, or plain `limactl`. |
Colima
Colima runs container runtimes on macOS (and Linux) with minimal setup. It's a higher-level
wrapper over Lima: it boots a small VM and provisions Docker,
containerd, Kubernetes and/or Incus inside it, then wires up the host client so docker (etc.)
"just works".
Scope: the canonical source is the repo's own docs (docs/INSTALL.md, docs/FAQ.md) plus
README usage. Behavior is version-gated in many places — keep the vX.Y.Z notes when
advising, since users run a range of versions. Check the user's version with colima version.
Quick start
brew install colima
colima start
docker run hello-world
Full install options (MacPorts, Nix, Arch, binary, source) → references/install.md.
Core commands
| Command | What it does |
|---|
colima start [profile] | Create/start the VM. Flags: --runtime, --kubernetes, --cpu, --memory, --disk, --edit, --env, --dns, --network-address, --vm-type, --foreground |
colima stop [--force] | Stop the VM. --force recovers a Broken status |
colima status | Show running status (incl. Docker socket path) |
colima list | List profiles and their status/arch/cpus/mem/disk/runtime |
colima restart | Stop + start (needed after editing mounts/config) |
colima delete [--data] | Delete the VM. --data also deletes container data (since v0.9.0 data lives on a separate disk) |
colima ssh [-- <cmd>] | Shell into the VM, or run one command |
colima start --edit | Start while editing the YAML config (since v0.4.0) |
colima template | Edit the default config template for new instances |
colima update | Update the container runtime in place (since v0.7.6) |
colima nerdctl ... | nerdctl wrapper for the containerd runtime |
colima model ... | Set up / run AI models (GPU, krunkit; since v0.10.0) |
colima version | Print the version (use it before applying version-gated advice) |
Profiles isolate independent VMs: colima start work operates on the work profile; default is default.
colima --help / colima start --help list everything.
Runtimes — chosen at start
Default is Docker. Switching the runtime requires re-creating the VM — a stop/start alone
does not change it: colima delete --data && colima start --runtime <new>.
- Docker (default):
colima start → docker ... works directly. Needs the docker client (brew install docker).
- Containerd:
colima start --runtime containerd → use colima nerdctl ... (run colima nerdctl install to add a nerdctl alias to $PATH).
- Kubernetes:
colima start --kubernetes (needs kubectl). Shares images with the chosen container runtime.
- Incus (v0.7.0+):
colima start --runtime incus → incus ....
- AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+):
colima start --runtime docker --vm-type krunkit then colima model run gemma3.
Per-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → references/runtimes.md.
Registry mirror (common task): colima start --registry-mirror <url> (repeatable) or --edit →
add under docker.registry-mirrors. For the client to honor mirrors, the host
~/.docker/daemon.json may also need the same entries. Details → references/runtimes.md.
Customizing the VM
Defaults: 2 CPUs, 2 GiB memory, 100 GiB disk. Customize via flags or the config file.
colima start --cpu 4 --memory 8 --disk 100
colima stop && colima start --cpu 4 --memory 8
colima start --vm-type=vz --vz-rosetta
Config files, profiles, COLIMA_HOME, passing env into the VM, Lima overrides → references/configuration.md.
Writing a bootstrap / CI / deploy script? See references/automation.md for non-interactive patterns:
idempotent start (colima status guard), readiness wait (docker info loop), DOCKER_HOST wiring so the
rest of the script targets Colima, --foreground for supervisors, teardown, and a GitHub Actions sketch.
Common gotchas (quick)
Cannot connect to the Docker daemon at unix:///var/run/docker.sock — an app isn't using Colima's
Docker context. Point it at Colima's socket (export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock")
or relink the socket. Details + socket location by version → references/troubleshooting.md.Broken status (e.g. after a macOS restart): colima stop --force, then colima start.- Docker bind mount shows empty — the host path must be under
/Users/$USER, or add it to the mounts
section of the config and colima restart. Paths with spaces are unsupported.
- Won't start / fatal error — re-run with
--verbose; common causes are no virtualization support or an
x86_64 Homebrew/Colima on Apple Silicon. See references/troubleshooting.md.
Full troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade
issues, deleting data) → references/troubleshooting.md.
References
references/install.md — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).references/configuration.md — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.references/runtimes.md — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.references/troubleshooting.md — startup failures, networking, mounts, disk, updates, deleting data.references/automation.md — non-interactive patterns for bootstrap / CI / deploy scripts.
