colima

# Colima Colima runs **container runtimes on macOS (and Linux) with minimal setup**. It's a higher-level wrapper over [Lima](https://github.com/lima-vm/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 ```sh brew install colima # + docker client if using Docker runtime: brew install docker colima start # boots the VM, Docker runtime by default docker run hello-world # docker client works with no extra setup ``` 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. ```sh colima start --cpu 4 --memory 8 --disk 100 # at create time colima stop && colima start --cpu 4 --memory 8 # change an existing VM (disk can only grow) colima start --vm-type=vz --vz-rosetta # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+) ``` 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.