{"owner":"abiosoft","repo":"colima","hasSkills":true,"totalSkillsCount":7,"totalTokensCount":7027,"categories":["anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["skills/references/install.md","skills/SKILL.md","skills/references/configuration.md","skills/README.md","skills/references/automation.md","skills/references/troubleshooting.md","skills/references/runtimes.md"],"skills":{"skills/references/install.md":"# Installing Colima\n\nSource: `docs/INSTALL.md`. Requires macOS 13+ (or Linux). Docker runtime also needs a docker client\n(`brew install docker`).\n\n## Homebrew\n\n```sh\nbrew install colima # stable\nbrew install --HEAD colima # development version\n```\n\n## MacPorts\n\n```sh\nsudo port install colima\n```\n\n## Nix\n\n```sh\nnix-env -i colima # install (stable only)\nnix-shell -p colima # or use only within a nix-shell\n```\n\n## Arch\n\n```sh\nsudo pacman -S qemu-full go docker # dependencies\nyay -S lima-bin colima-bin # Lima + Colima from AUR\n```\n\n## Binary\n\nBinaries ship with every [release](https://github.com/abiosoft/colima/releases).\n\n```sh\n# download binary\ncurl -LO https://github.com/abiosoft/colima/releases/latest/download/colima-$(uname)-$(uname -m)\n\n# install in $PATH\nsudo install colima-$(uname)-$(uname -m) /usr/local/bin/colima\n```\n\n## Building from source\n\nRequires [Go](https://golang.org).\n\n```sh\ngit clone https://github.com/abiosoft/colima\ncd colima\nmake\nsudo make install\n```\n\n## Notes\n\n- Colima requires **macOS 13 or newer**. On older macOS you may be able to build Colima and its\n dependencies ([Lima](https://github.com/lima-vm/lima), [Qemu](https://www.qemu.org/)) from source.\n- Both Intel and Apple Silicon Macs are supported.\n- Updating: `brew upgrade colima`, then `colima delete && colima start` to recreate the VM on the new\n image. The container runtime alone can be updated with `colima update` (v0.7.6+). See\n `troubleshooting.md` → updates.\n","skills/SKILL.md":"---\nname: colima\ndescription: >-\n Guide to using Colima — container runtimes (Docker, containerd, Kubernetes, Incus) on macOS\n and Linux via lightweight Lima VMs. Use this skill whenever Colima is (or should be) the\n container backend: installing Colima; `colima start/stop/status/delete/ssh`; picking or\n switching a runtime; the `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n error; Docker contexts and socket location; registry mirrors / insecure registries; buildx;\n bind or volume mounts that show up empty in the container; disk space recovery/resize;\n reachable VM IP; GPU / AI model workloads; config files, profiles and `COLIMA_HOME`; or a\n Colima VM that won't start. ALSO use it for **writing scripts that drive Colima** — bootstrap,\n dev-env, deploy, or CI scripts that bring Colima up non-interactively — because the skill has\n the correct flags, profile-specific socket paths, idempotent `colima start` guards, and\n readiness/teardown patterns that hand-written scripts routinely get wrong (e.g. inventing a\n non-existent flag or hardcoding the wrong docker socket). Prefer this over generic Docker\n advice whenever Colima is the daemon. This skill is specifically about **Colima** — not Docker\n Desktop, minikube, Kind, K3d, Rancher Desktop, OrbStack, Podman, or plain `limactl`.\n---\n\n# Colima\n\nColima runs **container runtimes on macOS (and Linux) with minimal setup**. It's a higher-level\nwrapper over [Lima](https://github.com/lima-vm/lima): it boots a small VM and provisions Docker,\ncontainerd, Kubernetes and/or Incus inside it, then wires up the host client so `docker` (etc.)\n\"just works\".\n\n> **Scope:** the canonical source is the repo's own docs (`docs/INSTALL.md`, `docs/FAQ.md`) plus\n> README usage. Behavior is **version-gated** in many places — keep the `vX.Y.Z` notes when\n> advising, since users run a range of versions. Check the user's version with `colima version`.\n\n## Quick start\n\n```sh\nbrew install colima # + docker client if using Docker runtime: brew install docker\ncolima start # boots the VM, Docker runtime by default\ndocker run hello-world # docker client works with no extra setup\n```\n\nFull install options (MacPorts, Nix, Arch, binary, source) → `references/install.md`.\n\n## Core commands\n\n| Command | What it does |\n|---|---|\n| `colima start [profile]` | Create/start the VM. Flags: `--runtime`, `--kubernetes`, `--cpu`, `--memory`, `--disk`, `--edit`, `--env`, `--dns`, `--network-address`, `--vm-type`, `--foreground` |\n| `colima stop [--force]` | Stop the VM. `--force` recovers a `Broken` status |\n| `colima status` | Show running status (incl. Docker socket path) |\n| `colima list` | List profiles and their status/arch/cpus/mem/disk/runtime |\n| `colima restart` | Stop + start (needed after editing mounts/config) |\n| `colima delete [--data]` | Delete the VM. `--data` also deletes container data (since v0.9.0 data lives on a separate disk) |\n| `colima ssh [-- ]` | Shell into the VM, or run one command |\n| `colima start --edit` | Start while editing the YAML config (since v0.4.0) |\n| `colima template` | Edit the default config template for new instances |\n| `colima update` | Update the container runtime in place (since v0.7.6) |\n| `colima nerdctl ...` | nerdctl wrapper for the containerd runtime |\n| `colima model ...` | Set up / run AI models (GPU, krunkit; since v0.10.0) |\n| `colima version` | Print the version (use it before applying version-gated advice) |\n\nProfiles isolate independent VMs: `colima start work` operates on the `work` profile; default is `default`.\n`colima --help` / `colima start --help` list everything.\n\n## Runtimes — chosen at `start`\n\nDefault is Docker. **Switching the runtime requires re-creating the VM** — a stop/start alone\ndoes not change it: `colima delete --data && colima start --runtime `.\n\n- **Docker** (default): `colima start` → `docker ...` works directly. Needs the docker client (`brew install docker`).\n- **Containerd**: `colima start --runtime containerd` → use `colima nerdctl ...` (run `colima nerdctl install` to add a `nerdctl` alias to `$PATH`).\n- **Kubernetes**: `colima start --kubernetes` (needs `kubectl`). Shares images with the chosen container runtime.\n- **Incus** (v0.7.0+): `colima start --runtime incus` → `incus ...`.\n- **AI models / GPU** (v0.10.0+, Apple Silicon, macOS 13+): `colima start --runtime docker --vm-type krunkit` then `colima model run gemma3`.\n\nPer-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → `references/runtimes.md`.\n\n> **Registry mirror** (common task): `colima start --registry-mirror ` (repeatable) or `--edit` →\n> add under `docker.registry-mirrors`. For the **client** to honor mirrors, the host\n> `~/.docker/daemon.json` may also need the same entries. Details → `references/runtimes.md`.\n\n## Customizing the VM\n\nDefaults: **2 CPUs, 2 GiB memory, 100 GiB disk**. Customize via flags or the config file.\n\n```sh\ncolima start --cpu 4 --memory 8 --disk 100 # at create time\ncolima stop && colima start --cpu 4 --memory 8 # change an existing VM (disk can only grow)\ncolima start --vm-type=vz --vz-rosetta # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+)\n```\n\nConfig files, profiles, `COLIMA_HOME`, passing env into the VM, Lima overrides → `references/configuration.md`.\n\n**Writing a bootstrap / CI / deploy script?** See `references/automation.md` for non-interactive patterns:\nidempotent start (`colima status` guard), readiness wait (`docker info` loop), `DOCKER_HOST` wiring so the\nrest of the script targets Colima, `--foreground` for supervisors, teardown, and a GitHub Actions sketch.\n\n## Common gotchas (quick)\n\n- **`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`** — an app isn't using Colima's\n Docker context. Point it at Colima's socket (`export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"`)\n or relink the socket. Details + socket location by version → `references/troubleshooting.md`.\n- **`Broken` status** (e.g. after a macOS restart): `colima stop --force`, then `colima start`.\n- **Docker bind mount shows empty** — the host path must be under `/Users/$USER`, or add it to the `mounts`\n section of the config and `colima restart`. Paths with spaces are unsupported.\n- **Won't start / fatal error** — re-run with `--verbose`; common causes are no virtualization support or an\n x86_64 Homebrew/Colima on Apple Silicon. See `references/troubleshooting.md`.\n\nFull troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade\nissues, deleting data) → `references/troubleshooting.md`.\n\n## References\n\n- `references/install.md` — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).\n- `references/configuration.md` — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.\n- `references/runtimes.md` — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.\n- `references/troubleshooting.md` — startup failures, networking, mounts, disk, updates, deleting data.\n- `references/automation.md` — non-interactive patterns for bootstrap / CI / deploy scripts.\n","skills/references/configuration.md":"# Configuration, profiles & file locations\n\nSource: `docs/FAQ.md`.\n\n## Config file (since v0.4.0)\n\nColima reads a YAML config instead of repeating CLI flags.\n\n```sh\ncolima start --edit # edit + start (one-off)\n```\n\n- Default config: `$HOME/.colima/default/colima.yaml`\n- Other profiles: `$HOME/.colima//colima.yaml`\n- Config location root is `$COLIMA_HOME` (defaults to `$HOME/.colima`).\n\n### Default template for new instances\n\n```sh\ncolima template # edit the default template\n```\n\nTemplate file: `$HOME/.colima/_templates/default.yaml`.\n\n### Choosing the editor\n\nSet `$EDITOR`, or pass `--editor`:\n\n```sh\ncolima start --edit --editor code # one-off\ncolima template --editor code # default config\n```\n\n## File-location environment variables (set on the host)\n\n| Variable | Description |\n|---|---|\n| `COLIMA_HOME` | Colima config directory (default `$HOME/.colima`) |\n| `COLIMA_CACHE_HOME` | Cache directory (host-specific default, see Go `os.UserCacheDir()`) |\n| `COLIMA_PROFILE` | Active profile name (default `default`) |\n| `DOCKER_CONFIG` | Docker client config dir (default `~/.docker`) |\n\n## Passing custom env vars into the VM\n\nConfig file:\n\n```yaml\nenv:\n MY_VAR: value\n```\n\nOr CLI:\n\n```sh\ncolima start --env MY_VAR=value\n# verify inside the VM:\ncolima ssh -- sh -c 'env | grep MY_VAR'\n```\n\n## Autostart\n\n- Foreground mode (since v0.5.6): `colima start --foreground`.\n- Installed via brew: `brew services start colima`.\n\n## Lima overrides (advanced users only)\n\nLima supports `override.yaml` (applied **before** the instance config) and `default.yaml` (applied\n**after**, as fallback defaults).\n\nOverride file: `$HOME/.colima/_lima/_config/override.yaml` (or `$LIMA_HOME/_config/override.yaml` if\n`LIMA_HOME` is set).\n\n> Overriding the **image** is not supported — Colima's image bundles dependencies a custom image would lack.\n\n### Example: provision scripts (run during VM boot)\n\n```yaml\n# $HOME/.colima/_lima/_config/override.yaml\nprovision:\n - mode: system\n script: |\n #!/bin/bash\n set -eux -o pipefail\n apt-get update && apt-get install -y curl\n```\n\nOr directly in `colima.yaml` via `colima start --edit`:\n\n```diff\n- provision: []\n+ provision:\n+ - mode: system\n+ script: |\n+ #!/bin/bash\n+ set -eux -o pipefail\n+ apt-get update && apt-get install -y curl\n```\n\n## Reachable VM IP (macOS only)\n\nDisabled by default (needs root, slower startup). Enable per-start or in config:\n\n```sh\ncolima start --network-address\n```\n\n```diff\nnetwork:\n- address: false\n+ address: true\n```\n\n(For Incus reachability from the host this is required — see `runtimes.md`.)\n","skills/README.md":"# Colima Agent Skill\n\n`SKILL.md` (plus the files in `references/`) is an **Agent Skill** — Markdown with YAML\nfrontmatter that an AI coding assistant loads on demand to give accurate, version-aware Colima\nhelp (install, runtimes, config, troubleshooting, and bootstrap/CI scripting) instead of generic\nDocker advice. It is plain documentation, distilled from this repo's own `docs/`; nothing executes.\n\n## How to use it\n\nThe skill is discovered from the assistant's *skills directory*, where each skill lives in its own\nfolder. Install it as a skill named `colima`:\n\n### Claude Code\n\n```sh\n# user-level (available in every project)\ncp -R skills ~/.claude/skills/colima\n\n# or project-level\ncp -R skills /.claude/skills/colima\n```\n\nStart a new session; the assistant loads the skill automatically when your task involves Colima\n(e.g. *\"my colima docker daemon isn't reachable from IntelliJ\"*, *\"write a CI script that brings\ncolima up with kubernetes\"*).\n\n### Other agents (Cursor, Kimi Code, …)\n\nAny tool that supports the `SKILL.md` format works the same way — copy this folder into that tool's\nskills directory, e.g.:\n\n```sh\ncp -R skills ~/.kimi-code/skills/colima # Kimi Code\n```\n\n…or point the tool's skills path at it directly (Kimi Code: `kimi --skills-dir `).\n\n## What's inside\n\n| File | Contents |\n|---|---|\n| `SKILL.md` | Quick reference + when-to-use (the part the model always sees). |\n| `references/install.md` | Homebrew, MacPorts, Nix, Arch, binary, source. |\n| `references/configuration.md` | Config files, profiles, `COLIMA_HOME`, env into the VM, Lima overrides. |\n| `references/runtimes.md` | Docker, containerd, Kubernetes, Incus, AI models; comparisons. |\n| `references/troubleshooting.md` | Daemon socket errors, `Broken` status, mounts, disk, networking, updates. |\n| `references/automation.md` | Non-interactive patterns for bootstrap / CI / deploy scripts. |\n\nThe content mirrors the canonical docs in [`../docs/`](../docs/); version-gated notes (e.g. `since\nvX.Y.Z`) are preserved, so advice stays correct across the versions users run.\n","skills/references/automation.md":"# Automation: bootstrap & deployment scripts\n\nPatterns for driving Colima **non-interactively** — dev-env bootstrap, CI, deploy scripts. The repo\ndocs are written for interactive use; this page adapts the same commands into script-safe building\nblocks. Pin behavior to a version (`colima version`) since flags vary.\n\n## 1. Wire the rest of the script to Colima's Docker\n\nA script that runs `docker`/`docker compose` after starting Colima must target Colima's daemon. Two ways:\n\n```sh\n# A) point this shell at Colima's socket (v0.4.0+ path)\nexport DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n\n# B) or make Colima the active context (it already sets itself default on start)\ndocker context use colima\n```\n\nDon't hardcode the socket blindly — `colima start` already makes itself the default context, so often no\nexport is needed. Use the explicit `DOCKER_HOST` when the script runs tools that ignore Docker contexts\n(see `troubleshooting.md`). Confirm the path with `colima status`.\n\n## 2. Idempotent start\n\nRe-running the script shouldn't fail if Colima is already up. `colima status` exits non-zero when the\nprofile isn't running:\n\n```sh\n#!/usr/bin/env bash\nset -euo pipefail\n\nPROFILE=\"${COLIMA_PROFILE:-default}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" \\\n --cpu 4 --memory 8 --disk 100 \\\n --runtime docker\nelse\n echo \"colima '$PROFILE' already running\"\nfi\n```\n\nUse a dedicated `--profile` to isolate the script's VM from a developer's `default` one (and to allow\nparallel CI jobs).\n\n## 3. Wait for readiness\n\n`colima start` returns when the VM is provisioned, but in CI it's worth confirming the daemon actually\nanswers before deploying:\n\n```sh\nfor i in $(seq 1 30); do\n if docker info >/dev/null 2>&1; then break; fi\n echo \"waiting for docker... ($i)\"; sleep 2\ndone\ndocker info >/dev/null # final check; fails the script if still not ready\n```\n\n## 4. Non-interactive / CI notes\n\n- **No prompts:** lifecycle commands are non-interactive except destructive ones — use `colima delete --force`.\n- **Foreground (v0.5.6+):** `colima start --foreground` keeps Colima in the foreground; useful under a\n process supervisor (launchd/systemd) or a CI step that owns the lifecycle. Without it, `colima start`\n backgrounds the VM and returns.\n- **Config over flags:** for reproducible environments, commit a `colima.yaml` and apply it with\n `colima start --edit` locally, or bake defaults via `colima template`. See `configuration.md`.\n- **Env into the VM:** `colima start --env KEY=value` (repeatable) or the `env:` config block.\n\n## 5. Teardown\n\n```sh\ncolima stop --profile \"$PROFILE\" # stop, keep the VM\ncolima delete --force --profile \"$PROFILE\" # remove the VM (data on separate disk since v0.9.0 is kept)\ncolima delete --force --data --profile \"$PROFILE\" # also wipe container data\n```\n\n## 6. Bootstrap script skeleton\n\n```sh\n#!/usr/bin/env bash\n# Bring up Colima (docker + kubernetes), make docker target it, deploy.\nset -euo pipefail\nPROFILE=\"${COLIMA_PROFILE:-ci}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" --kubernetes --cpu 4 --memory 8 --disk 60\nfi\n\nexport DOCKER_HOST=\"unix://$HOME/.colima/$PROFILE/docker.sock\" # profile-specific socket\nfor i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done\n\ndocker compose up -d # or: kubectl apply -f k8s/\n# ... deploy / test ...\n\n# teardown (e.g. CI trap):\n# trap 'colima delete --force --profile \"$PROFILE\"' EXIT\n```\n\n> Note the **profile-specific socket** path `$HOME/.colima//docker.sock` — only the `default`\n> profile lives at `.../default/docker.sock`.\n\n## 7. macOS CI (GitHub Actions sketch)\n\nColima needs a macOS runner (nested virtualization). Rough shape:\n\n```yaml\njobs:\n test:\n runs-on: macos-14\n steps:\n - uses: actions/checkout@v4\n - run: brew install colima docker\n - run: colima start --cpu 3 --memory 6 --disk 30\n - run: docker info && docker compose up -d\n # colima is the default context, so docker just works\n```\n\nPin Colima/runner versions for reproducibility; resource flags must fit the runner's limits.\n","skills/references/troubleshooting.md":"# Troubleshooting\n\nSource: `docs/FAQ.md`. Many fixes are version-gated — check `colima version` first.\n\n## `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n\nColima uses Docker contexts and sets itself as the default context on start, but some apps ignore\ncontexts. Fix with any of (confirm the socket path first — see socket location in `runtimes.md`):\n\n1. Set an app-specific Docker socket path if supported (e.g. JetBrains IDEs).\n2. Point `DOCKER_HOST` at Colima's socket:\n ```sh\n export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n ```\n3. Link Colima's socket to the default path (**may break other Docker servers**):\n ```sh\n sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock\n ```\n\n## Colima not starting\n\n### Broken status\n\n`colima list` shows `Broken` (often after a macOS restart). Force-stop, then start:\n\n```sh\ncolima stop --force\ncolima start\n```\n\n### `FATA[0000] error starting vm: error at 'starting': exit status 1`\n\nEnable debug logging to investigate:\n\n```sh\ncolima start --verbose\n```\n\nIf the log shows `exiting, status={Running:false Degraded:false Exiting:true ...}`, it's almost always\neither (1) a device without virtualization support, or (2) an x86_64 Homebrew/Colima on an Apple Silicon (M1) device.\n\n### Issues after an upgrade\n\nTest with a separate profile; if it starts cleanly, reset the default profile:\n\n```sh\ncolima start debug # separate profile\n# if that works:\ncolima delete\ncolima start\n```\n\n## Colima cannot access the internet\n\nUsually DNS. Try custom DNS servers and verify from inside the VM:\n\n```sh\ncolima start --dns 8.8.8.8 --dns 1.1.1.1\ncolima ssh -- ping -c4 google.com\n```\n\n## Docker Compose / Buildx `runc ... cgroup ... invalid argument` (v0.5.6 or lower)\n\nWorkaround from v0.5.6: start with `--cgroups-v2`. **Fixed in v0.6.0.**\n\n```sh\ncolima start --cgroups-v2\n```\n\n## Docker bind mount shows empty\n\nBind-mounting a host path **not** under `/Users/$USER` starts the container without error but the\nmountpoint is empty. Mount it on the VM first: edit `$HOME/.colima/default/colima.yaml`, add the path\nto the `mounts` section (examples are in the file), then `colima restart` and re-run the container.\n\n## Mount path with spaces is not supported\n\nPaths with spaces (e.g. `/Volumes/External HD`) aren't supported by the underlying Lima runtime; Colima\nrejects them at startup with a clear error. Workaround: mount a parent dir without spaces, or rename/alias\nthe volume. See [#1471](https://github.com/abiosoft/colima/issues/1471).\n\n## Disk space\n\n### Recover space\n\nFree space in the VM with `docker system prune` or by removing containers. On v0.4.x or lower this\ndoesn't reflect on the host.\n\n- v0.5.0+: unused VM disk space is released on startup — a `colima restart` suffices.\n- v0.5.0+: manual trim:\n ```sh\n colima ssh -- sudo fstrim -a # add -v for verbose\n ```\n\n### Increase disk size (v0.5.3+)\n\nDisk grows on startup from `colima.yaml`:\n\n```diff\n- disk: 150\n+ disk: 250\n```\n\n## Updating\n\n- **Colima itself:** `brew upgrade colima`, then recreate the VM to use the new image:\n ```sh\n colima delete\n colima start\n ```\n Test an upgrade safely on a separate profile: `colima start debug`.\n- **Container runtime only (v0.7.6+):** `colima update` — updates Docker/containerd without updating\n Colima or waiting for a release.\n\n## Accessing the VM directly\n\n```sh\ncolima ssh # interactive shell\ncolima ssh -- uname -a # one-off command\n```\n\n## Deleting container data\n\nSince v0.9.0 container data lives on a separate disk, so `colima delete` preserves it (reinstated on\n`colima start`). To wipe everything including data:\n\n```sh\ncolima delete --data\n```\n","skills/references/runtimes.md":"# Runtimes: Docker, Containerd, Kubernetes, Incus, AI\n\nSources: `README.md` (usage) + `docs/FAQ.md` (config/details). Runtime is chosen at `colima start`\n(default Docker). **Switching to a different runtime requires re-creating the VM** — a stop/start\nalone does not change it:\n\n```sh\ncolima delete --data && colima start --runtime \n```\n\n## Docker\n\n```sh\ncolima start # docker runtime\ndocker run hello-world\ndocker ps\n```\n\nColima leverages **Docker contexts** and can run alongside Docker Desktop (since v0.3.0); it makes\nitself the default context on startup.\n\n### Socket location (version-gated)\n\n| Version | Docker socket |\n|---|---|\n| v0.3.4 or older | `$HOME/.colima/docker.sock` |\n| v0.4.0 or newer | `$HOME/.colima/default/docker.sock` |\n\nAlso shown by `colima status`.\n\n### Docker contexts\n\n```sh\ndocker context list # list contexts\ndocker context use # switch active context\n```\n\n### Customizing the Docker daemon (insecure registries, mirrors)\n\n- v0.3.4 or lower: edit `$HOME/.colima/docker/daemon.json` (generated on first start), then restart.\n- v0.4.0+: `colima start --edit` and add under the `docker:` section:\n\n ```diff\n - docker: {}\n + docker:\n + insecure-registries:\n + - myregistry.com:5000\n + registry-mirrors:\n + - https://my.dockerhub.mirror.something\n ```\n\nRegistry mirrors can also be set at start (repeatable flag), no editing needed:\n\n```sh\ncolima start --registry-mirror https://my.dockerhub.mirror.something\n```\n\n> The host `~/.docker/daemon.json` may also need matching changes for the **client** to honor some\n> values (e.g. registry mirrors). Use `colima template` to bake changes into all new instances.\n\n### Buildx plugin missing\n\n```sh\nbrew install docker-buildx\nmkdir -p ~/.docker/cli-plugins\nln -sfn $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx\ndocker buildx version\n```\n\n## Containerd\n\n```sh\ncolima start --runtime containerd\ncolima nerdctl install # add a `nerdctl` alias to $PATH (recommended)\nnerdctl run hello-world\nnerdctl ps\n```\n\n### Config files (first start with containerd)\n\n| File | Location |\n|---|---|\n| Containerd config | `~/.config/containerd/config.toml` |\n| BuildKit config | `~/.config/buildkit/buildkitd.toml` |\n\nShared across profiles; edit then `colima stop && colima start --runtime containerd`.\n`$XDG_CONFIG_HOME` is respected if set.\n\n**Per-profile override:** place the file at `$HOME/.colima//containerd/config.toml` (or\n`buildkitd.toml`). Resolution order: per-profile override → central (`~/.config/...`) → embedded default.\n\n## Kubernetes\n\n```sh\ncolima start --kubernetes # needs kubectl (brew install kubectl)\nkubectl run caddy --image=caddy\nkubectl get pods\n```\n\nImage registry sharing: Docker runtime — images built/pulled with Docker are available to Kubernetes;\nContainerd runtime — images in the `k8s.io` namespace are available.\n\n## Incus (v0.7.0+)\n\n```sh\ncolima start --runtime incus # needs incus (brew install incus)\nincus launch images:alpine/edge\nincus list\n```\n\nRunning **VMs** on Incus needs an M3 or newer Apple Silicon device. Incus instances aren't reachable\nfrom the host by default (v0.10.0+) — enable network address:\n\n```sh\ncolima stop\ncolima start --network-address\n```\n\n## AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+)\n\nUses the `krunkit` VM type (install [krunkit](https://github.com/containers/krunkit#installation) first).\n\n```sh\ncolima start --runtime docker --vm-type krunkit\ncolima model setup\ncolima model run gemma3\n```\n\nTwo runner backends: **Docker Model Runner** (default — Docker AI Registry + HuggingFace) and\n**Ramalama** (HuggingFace + Ollama). Registry examples:\n\n```sh\ncolima model run gemma3 # Docker AI Registry (default, no prefix)\ncolima model run hf://tinyllama # HuggingFace\ncolima model run ollama://tinyllama --runner ramalama # Ollama (ramalama runner)\n```\n\n`colima model --help` for more.\n\n## How Colima compares\n\n- **vs Lima:** Colima is a higher-level use of Lima — it uses Lima to provide Docker/Containerd/Kubernetes.\n- **vs minikube/Kind/K3d (Kubernetes):** those suit multiple clusters or when you don't need Docker and\n Kubernetes to share images/runtime. Colima with Docker runtime is fully compatible with them.\n- **vs minikube (Docker):** minikube can expose its Docker via `minikube docker-env`, but Kubernetes is\n not optional there, and its free macOS drivers fall short on performance/port-forwarding/volumes for\n Docker-only use.\n\n## Distro / underlying VM\n\n- v0.5.6 and lower: lightweight Alpine image; optional Ubuntu **layer** via `colima start --layer=true`\n (with the layer, `ssh`/`ssh-config` route to the layer; use `--layer=false` to reach the underlying VM).\n- v0.6.0 and newer: Ubuntu is the underlying image; other distros aren't supported.\n"},"files":{"skills/references/install.md":"# Installing Colima\n\nSource: `docs/INSTALL.md`. Requires macOS 13+ (or Linux). Docker runtime also needs a docker client\n(`brew install docker`).\n\n## Homebrew\n\n```sh\nbrew install colima # stable\nbrew install --HEAD colima # development version\n```\n\n## MacPorts\n\n```sh\nsudo port install colima\n```\n\n## Nix\n\n```sh\nnix-env -i colima # install (stable only)\nnix-shell -p colima # or use only within a nix-shell\n```\n\n## Arch\n\n```sh\nsudo pacman -S qemu-full go docker # dependencies\nyay -S lima-bin colima-bin # Lima + Colima from AUR\n```\n\n## Binary\n\nBinaries ship with every [release](https://github.com/abiosoft/colima/releases).\n\n```sh\n# download binary\ncurl -LO https://github.com/abiosoft/colima/releases/latest/download/colima-$(uname)-$(uname -m)\n\n# install in $PATH\nsudo install colima-$(uname)-$(uname -m) /usr/local/bin/colima\n```\n\n## Building from source\n\nRequires [Go](https://golang.org).\n\n```sh\ngit clone https://github.com/abiosoft/colima\ncd colima\nmake\nsudo make install\n```\n\n## Notes\n\n- Colima requires **macOS 13 or newer**. On older macOS you may be able to build Colima and its\n dependencies ([Lima](https://github.com/lima-vm/lima), [Qemu](https://www.qemu.org/)) from source.\n- Both Intel and Apple Silicon Macs are supported.\n- Updating: `brew upgrade colima`, then `colima delete && colima start` to recreate the VM on the new\n image. The container runtime alone can be updated with `colima update` (v0.7.6+). See\n `troubleshooting.md` → updates.\n","skills/SKILL.md":"---\nname: colima\ndescription: >-\n Guide to using Colima — container runtimes (Docker, containerd, Kubernetes, Incus) on macOS\n and Linux via lightweight Lima VMs. Use this skill whenever Colima is (or should be) the\n container backend: installing Colima; `colima start/stop/status/delete/ssh`; picking or\n switching a runtime; the `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n error; Docker contexts and socket location; registry mirrors / insecure registries; buildx;\n bind or volume mounts that show up empty in the container; disk space recovery/resize;\n reachable VM IP; GPU / AI model workloads; config files, profiles and `COLIMA_HOME`; or a\n Colima VM that won't start. ALSO use it for **writing scripts that drive Colima** — bootstrap,\n dev-env, deploy, or CI scripts that bring Colima up non-interactively — because the skill has\n the correct flags, profile-specific socket paths, idempotent `colima start` guards, and\n readiness/teardown patterns that hand-written scripts routinely get wrong (e.g. inventing a\n non-existent flag or hardcoding the wrong docker socket). Prefer this over generic Docker\n advice whenever Colima is the daemon. This skill is specifically about **Colima** — not Docker\n Desktop, minikube, Kind, K3d, Rancher Desktop, OrbStack, Podman, or plain `limactl`.\n---\n\n# Colima\n\nColima runs **container runtimes on macOS (and Linux) with minimal setup**. It's a higher-level\nwrapper over [Lima](https://github.com/lima-vm/lima): it boots a small VM and provisions Docker,\ncontainerd, Kubernetes and/or Incus inside it, then wires up the host client so `docker` (etc.)\n\"just works\".\n\n> **Scope:** the canonical source is the repo's own docs (`docs/INSTALL.md`, `docs/FAQ.md`) plus\n> README usage. Behavior is **version-gated** in many places — keep the `vX.Y.Z` notes when\n> advising, since users run a range of versions. Check the user's version with `colima version`.\n\n## Quick start\n\n```sh\nbrew install colima # + docker client if using Docker runtime: brew install docker\ncolima start # boots the VM, Docker runtime by default\ndocker run hello-world # docker client works with no extra setup\n```\n\nFull install options (MacPorts, Nix, Arch, binary, source) → `references/install.md`.\n\n## Core commands\n\n| Command | What it does |\n|---|---|\n| `colima start [profile]` | Create/start the VM. Flags: `--runtime`, `--kubernetes`, `--cpu`, `--memory`, `--disk`, `--edit`, `--env`, `--dns`, `--network-address`, `--vm-type`, `--foreground` |\n| `colima stop [--force]` | Stop the VM. `--force` recovers a `Broken` status |\n| `colima status` | Show running status (incl. Docker socket path) |\n| `colima list` | List profiles and their status/arch/cpus/mem/disk/runtime |\n| `colima restart` | Stop + start (needed after editing mounts/config) |\n| `colima delete [--data]` | Delete the VM. `--data` also deletes container data (since v0.9.0 data lives on a separate disk) |\n| `colima ssh [-- ]` | Shell into the VM, or run one command |\n| `colima start --edit` | Start while editing the YAML config (since v0.4.0) |\n| `colima template` | Edit the default config template for new instances |\n| `colima update` | Update the container runtime in place (since v0.7.6) |\n| `colima nerdctl ...` | nerdctl wrapper for the containerd runtime |\n| `colima model ...` | Set up / run AI models (GPU, krunkit; since v0.10.0) |\n| `colima version` | Print the version (use it before applying version-gated advice) |\n\nProfiles isolate independent VMs: `colima start work` operates on the `work` profile; default is `default`.\n`colima --help` / `colima start --help` list everything.\n\n## Runtimes — chosen at `start`\n\nDefault is Docker. **Switching the runtime requires re-creating the VM** — a stop/start alone\ndoes not change it: `colima delete --data && colima start --runtime `.\n\n- **Docker** (default): `colima start` → `docker ...` works directly. Needs the docker client (`brew install docker`).\n- **Containerd**: `colima start --runtime containerd` → use `colima nerdctl ...` (run `colima nerdctl install` to add a `nerdctl` alias to `$PATH`).\n- **Kubernetes**: `colima start --kubernetes` (needs `kubectl`). Shares images with the chosen container runtime.\n- **Incus** (v0.7.0+): `colima start --runtime incus` → `incus ...`.\n- **AI models / GPU** (v0.10.0+, Apple Silicon, macOS 13+): `colima start --runtime docker --vm-type krunkit` then `colima model run gemma3`.\n\nPer-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → `references/runtimes.md`.\n\n> **Registry mirror** (common task): `colima start --registry-mirror ` (repeatable) or `--edit` →\n> add under `docker.registry-mirrors`. For the **client** to honor mirrors, the host\n> `~/.docker/daemon.json` may also need the same entries. Details → `references/runtimes.md`.\n\n## Customizing the VM\n\nDefaults: **2 CPUs, 2 GiB memory, 100 GiB disk**. Customize via flags or the config file.\n\n```sh\ncolima start --cpu 4 --memory 8 --disk 100 # at create time\ncolima stop && colima start --cpu 4 --memory 8 # change an existing VM (disk can only grow)\ncolima start --vm-type=vz --vz-rosetta # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+)\n```\n\nConfig files, profiles, `COLIMA_HOME`, passing env into the VM, Lima overrides → `references/configuration.md`.\n\n**Writing a bootstrap / CI / deploy script?** See `references/automation.md` for non-interactive patterns:\nidempotent start (`colima status` guard), readiness wait (`docker info` loop), `DOCKER_HOST` wiring so the\nrest of the script targets Colima, `--foreground` for supervisors, teardown, and a GitHub Actions sketch.\n\n## Common gotchas (quick)\n\n- **`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`** — an app isn't using Colima's\n Docker context. Point it at Colima's socket (`export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"`)\n or relink the socket. Details + socket location by version → `references/troubleshooting.md`.\n- **`Broken` status** (e.g. after a macOS restart): `colima stop --force`, then `colima start`.\n- **Docker bind mount shows empty** — the host path must be under `/Users/$USER`, or add it to the `mounts`\n section of the config and `colima restart`. Paths with spaces are unsupported.\n- **Won't start / fatal error** — re-run with `--verbose`; common causes are no virtualization support or an\n x86_64 Homebrew/Colima on Apple Silicon. See `references/troubleshooting.md`.\n\nFull troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade\nissues, deleting data) → `references/troubleshooting.md`.\n\n## References\n\n- `references/install.md` — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).\n- `references/configuration.md` — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.\n- `references/runtimes.md` — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.\n- `references/troubleshooting.md` — startup failures, networking, mounts, disk, updates, deleting data.\n- `references/automation.md` — non-interactive patterns for bootstrap / CI / deploy scripts.\n","skills/references/configuration.md":"# Configuration, profiles & file locations\n\nSource: `docs/FAQ.md`.\n\n## Config file (since v0.4.0)\n\nColima reads a YAML config instead of repeating CLI flags.\n\n```sh\ncolima start --edit # edit + start (one-off)\n```\n\n- Default config: `$HOME/.colima/default/colima.yaml`\n- Other profiles: `$HOME/.colima//colima.yaml`\n- Config location root is `$COLIMA_HOME` (defaults to `$HOME/.colima`).\n\n### Default template for new instances\n\n```sh\ncolima template # edit the default template\n```\n\nTemplate file: `$HOME/.colima/_templates/default.yaml`.\n\n### Choosing the editor\n\nSet `$EDITOR`, or pass `--editor`:\n\n```sh\ncolima start --edit --editor code # one-off\ncolima template --editor code # default config\n```\n\n## File-location environment variables (set on the host)\n\n| Variable | Description |\n|---|---|\n| `COLIMA_HOME` | Colima config directory (default `$HOME/.colima`) |\n| `COLIMA_CACHE_HOME` | Cache directory (host-specific default, see Go `os.UserCacheDir()`) |\n| `COLIMA_PROFILE` | Active profile name (default `default`) |\n| `DOCKER_CONFIG` | Docker client config dir (default `~/.docker`) |\n\n## Passing custom env vars into the VM\n\nConfig file:\n\n```yaml\nenv:\n MY_VAR: value\n```\n\nOr CLI:\n\n```sh\ncolima start --env MY_VAR=value\n# verify inside the VM:\ncolima ssh -- sh -c 'env | grep MY_VAR'\n```\n\n## Autostart\n\n- Foreground mode (since v0.5.6): `colima start --foreground`.\n- Installed via brew: `brew services start colima`.\n\n## Lima overrides (advanced users only)\n\nLima supports `override.yaml` (applied **before** the instance config) and `default.yaml` (applied\n**after**, as fallback defaults).\n\nOverride file: `$HOME/.colima/_lima/_config/override.yaml` (or `$LIMA_HOME/_config/override.yaml` if\n`LIMA_HOME` is set).\n\n> Overriding the **image** is not supported — Colima's image bundles dependencies a custom image would lack.\n\n### Example: provision scripts (run during VM boot)\n\n```yaml\n# $HOME/.colima/_lima/_config/override.yaml\nprovision:\n - mode: system\n script: |\n #!/bin/bash\n set -eux -o pipefail\n apt-get update && apt-get install -y curl\n```\n\nOr directly in `colima.yaml` via `colima start --edit`:\n\n```diff\n- provision: []\n+ provision:\n+ - mode: system\n+ script: |\n+ #!/bin/bash\n+ set -eux -o pipefail\n+ apt-get update && apt-get install -y curl\n```\n\n## Reachable VM IP (macOS only)\n\nDisabled by default (needs root, slower startup). Enable per-start or in config:\n\n```sh\ncolima start --network-address\n```\n\n```diff\nnetwork:\n- address: false\n+ address: true\n```\n\n(For Incus reachability from the host this is required — see `runtimes.md`.)\n","skills/README.md":"# Colima Agent Skill\n\n`SKILL.md` (plus the files in `references/`) is an **Agent Skill** — Markdown with YAML\nfrontmatter that an AI coding assistant loads on demand to give accurate, version-aware Colima\nhelp (install, runtimes, config, troubleshooting, and bootstrap/CI scripting) instead of generic\nDocker advice. It is plain documentation, distilled from this repo's own `docs/`; nothing executes.\n\n## How to use it\n\nThe skill is discovered from the assistant's *skills directory*, where each skill lives in its own\nfolder. Install it as a skill named `colima`:\n\n### Claude Code\n\n```sh\n# user-level (available in every project)\ncp -R skills ~/.claude/skills/colima\n\n# or project-level\ncp -R skills /.claude/skills/colima\n```\n\nStart a new session; the assistant loads the skill automatically when your task involves Colima\n(e.g. *\"my colima docker daemon isn't reachable from IntelliJ\"*, *\"write a CI script that brings\ncolima up with kubernetes\"*).\n\n### Other agents (Cursor, Kimi Code, …)\n\nAny tool that supports the `SKILL.md` format works the same way — copy this folder into that tool's\nskills directory, e.g.:\n\n```sh\ncp -R skills ~/.kimi-code/skills/colima # Kimi Code\n```\n\n…or point the tool's skills path at it directly (Kimi Code: `kimi --skills-dir `).\n\n## What's inside\n\n| File | Contents |\n|---|---|\n| `SKILL.md` | Quick reference + when-to-use (the part the model always sees). |\n| `references/install.md` | Homebrew, MacPorts, Nix, Arch, binary, source. |\n| `references/configuration.md` | Config files, profiles, `COLIMA_HOME`, env into the VM, Lima overrides. |\n| `references/runtimes.md` | Docker, containerd, Kubernetes, Incus, AI models; comparisons. |\n| `references/troubleshooting.md` | Daemon socket errors, `Broken` status, mounts, disk, networking, updates. |\n| `references/automation.md` | Non-interactive patterns for bootstrap / CI / deploy scripts. |\n\nThe content mirrors the canonical docs in [`../docs/`](../docs/); version-gated notes (e.g. `since\nvX.Y.Z`) are preserved, so advice stays correct across the versions users run.\n","skills/references/automation.md":"# Automation: bootstrap & deployment scripts\n\nPatterns for driving Colima **non-interactively** — dev-env bootstrap, CI, deploy scripts. The repo\ndocs are written for interactive use; this page adapts the same commands into script-safe building\nblocks. Pin behavior to a version (`colima version`) since flags vary.\n\n## 1. Wire the rest of the script to Colima's Docker\n\nA script that runs `docker`/`docker compose` after starting Colima must target Colima's daemon. Two ways:\n\n```sh\n# A) point this shell at Colima's socket (v0.4.0+ path)\nexport DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n\n# B) or make Colima the active context (it already sets itself default on start)\ndocker context use colima\n```\n\nDon't hardcode the socket blindly — `colima start` already makes itself the default context, so often no\nexport is needed. Use the explicit `DOCKER_HOST` when the script runs tools that ignore Docker contexts\n(see `troubleshooting.md`). Confirm the path with `colima status`.\n\n## 2. Idempotent start\n\nRe-running the script shouldn't fail if Colima is already up. `colima status` exits non-zero when the\nprofile isn't running:\n\n```sh\n#!/usr/bin/env bash\nset -euo pipefail\n\nPROFILE=\"${COLIMA_PROFILE:-default}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" \\\n --cpu 4 --memory 8 --disk 100 \\\n --runtime docker\nelse\n echo \"colima '$PROFILE' already running\"\nfi\n```\n\nUse a dedicated `--profile` to isolate the script's VM from a developer's `default` one (and to allow\nparallel CI jobs).\n\n## 3. Wait for readiness\n\n`colima start` returns when the VM is provisioned, but in CI it's worth confirming the daemon actually\nanswers before deploying:\n\n```sh\nfor i in $(seq 1 30); do\n if docker info >/dev/null 2>&1; then break; fi\n echo \"waiting for docker... ($i)\"; sleep 2\ndone\ndocker info >/dev/null # final check; fails the script if still not ready\n```\n\n## 4. Non-interactive / CI notes\n\n- **No prompts:** lifecycle commands are non-interactive except destructive ones — use `colima delete --force`.\n- **Foreground (v0.5.6+):** `colima start --foreground` keeps Colima in the foreground; useful under a\n process supervisor (launchd/systemd) or a CI step that owns the lifecycle. Without it, `colima start`\n backgrounds the VM and returns.\n- **Config over flags:** for reproducible environments, commit a `colima.yaml` and apply it with\n `colima start --edit` locally, or bake defaults via `colima template`. See `configuration.md`.\n- **Env into the VM:** `colima start --env KEY=value` (repeatable) or the `env:` config block.\n\n## 5. Teardown\n\n```sh\ncolima stop --profile \"$PROFILE\" # stop, keep the VM\ncolima delete --force --profile \"$PROFILE\" # remove the VM (data on separate disk since v0.9.0 is kept)\ncolima delete --force --data --profile \"$PROFILE\" # also wipe container data\n```\n\n## 6. Bootstrap script skeleton\n\n```sh\n#!/usr/bin/env bash\n# Bring up Colima (docker + kubernetes), make docker target it, deploy.\nset -euo pipefail\nPROFILE=\"${COLIMA_PROFILE:-ci}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" --kubernetes --cpu 4 --memory 8 --disk 60\nfi\n\nexport DOCKER_HOST=\"unix://$HOME/.colima/$PROFILE/docker.sock\" # profile-specific socket\nfor i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done\n\ndocker compose up -d # or: kubectl apply -f k8s/\n# ... deploy / test ...\n\n# teardown (e.g. CI trap):\n# trap 'colima delete --force --profile \"$PROFILE\"' EXIT\n```\n\n> Note the **profile-specific socket** path `$HOME/.colima//docker.sock` — only the `default`\n> profile lives at `.../default/docker.sock`.\n\n## 7. macOS CI (GitHub Actions sketch)\n\nColima needs a macOS runner (nested virtualization). Rough shape:\n\n```yaml\njobs:\n test:\n runs-on: macos-14\n steps:\n - uses: actions/checkout@v4\n - run: brew install colima docker\n - run: colima start --cpu 3 --memory 6 --disk 30\n - run: docker info && docker compose up -d\n # colima is the default context, so docker just works\n```\n\nPin Colima/runner versions for reproducibility; resource flags must fit the runner's limits.\n","skills/references/troubleshooting.md":"# Troubleshooting\n\nSource: `docs/FAQ.md`. Many fixes are version-gated — check `colima version` first.\n\n## `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n\nColima uses Docker contexts and sets itself as the default context on start, but some apps ignore\ncontexts. Fix with any of (confirm the socket path first — see socket location in `runtimes.md`):\n\n1. Set an app-specific Docker socket path if supported (e.g. JetBrains IDEs).\n2. Point `DOCKER_HOST` at Colima's socket:\n ```sh\n export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n ```\n3. Link Colima's socket to the default path (**may break other Docker servers**):\n ```sh\n sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock\n ```\n\n## Colima not starting\n\n### Broken status\n\n`colima list` shows `Broken` (often after a macOS restart). Force-stop, then start:\n\n```sh\ncolima stop --force\ncolima start\n```\n\n### `FATA[0000] error starting vm: error at 'starting': exit status 1`\n\nEnable debug logging to investigate:\n\n```sh\ncolima start --verbose\n```\n\nIf the log shows `exiting, status={Running:false Degraded:false Exiting:true ...}`, it's almost always\neither (1) a device without virtualization support, or (2) an x86_64 Homebrew/Colima on an Apple Silicon (M1) device.\n\n### Issues after an upgrade\n\nTest with a separate profile; if it starts cleanly, reset the default profile:\n\n```sh\ncolima start debug # separate profile\n# if that works:\ncolima delete\ncolima start\n```\n\n## Colima cannot access the internet\n\nUsually DNS. Try custom DNS servers and verify from inside the VM:\n\n```sh\ncolima start --dns 8.8.8.8 --dns 1.1.1.1\ncolima ssh -- ping -c4 google.com\n```\n\n## Docker Compose / Buildx `runc ... cgroup ... invalid argument` (v0.5.6 or lower)\n\nWorkaround from v0.5.6: start with `--cgroups-v2`. **Fixed in v0.6.0.**\n\n```sh\ncolima start --cgroups-v2\n```\n\n## Docker bind mount shows empty\n\nBind-mounting a host path **not** under `/Users/$USER` starts the container without error but the\nmountpoint is empty. Mount it on the VM first: edit `$HOME/.colima/default/colima.yaml`, add the path\nto the `mounts` section (examples are in the file), then `colima restart` and re-run the container.\n\n## Mount path with spaces is not supported\n\nPaths with spaces (e.g. `/Volumes/External HD`) aren't supported by the underlying Lima runtime; Colima\nrejects them at startup with a clear error. Workaround: mount a parent dir without spaces, or rename/alias\nthe volume. See [#1471](https://github.com/abiosoft/colima/issues/1471).\n\n## Disk space\n\n### Recover space\n\nFree space in the VM with `docker system prune` or by removing containers. On v0.4.x or lower this\ndoesn't reflect on the host.\n\n- v0.5.0+: unused VM disk space is released on startup — a `colima restart` suffices.\n- v0.5.0+: manual trim:\n ```sh\n colima ssh -- sudo fstrim -a # add -v for verbose\n ```\n\n### Increase disk size (v0.5.3+)\n\nDisk grows on startup from `colima.yaml`:\n\n```diff\n- disk: 150\n+ disk: 250\n```\n\n## Updating\n\n- **Colima itself:** `brew upgrade colima`, then recreate the VM to use the new image:\n ```sh\n colima delete\n colima start\n ```\n Test an upgrade safely on a separate profile: `colima start debug`.\n- **Container runtime only (v0.7.6+):** `colima update` — updates Docker/containerd without updating\n Colima or waiting for a release.\n\n## Accessing the VM directly\n\n```sh\ncolima ssh # interactive shell\ncolima ssh -- uname -a # one-off command\n```\n\n## Deleting container data\n\nSince v0.9.0 container data lives on a separate disk, so `colima delete` preserves it (reinstated on\n`colima start`). To wipe everything including data:\n\n```sh\ncolima delete --data\n```\n","skills/references/runtimes.md":"# Runtimes: Docker, Containerd, Kubernetes, Incus, AI\n\nSources: `README.md` (usage) + `docs/FAQ.md` (config/details). Runtime is chosen at `colima start`\n(default Docker). **Switching to a different runtime requires re-creating the VM** — a stop/start\nalone does not change it:\n\n```sh\ncolima delete --data && colima start --runtime \n```\n\n## Docker\n\n```sh\ncolima start # docker runtime\ndocker run hello-world\ndocker ps\n```\n\nColima leverages **Docker contexts** and can run alongside Docker Desktop (since v0.3.0); it makes\nitself the default context on startup.\n\n### Socket location (version-gated)\n\n| Version | Docker socket |\n|---|---|\n| v0.3.4 or older | `$HOME/.colima/docker.sock` |\n| v0.4.0 or newer | `$HOME/.colima/default/docker.sock` |\n\nAlso shown by `colima status`.\n\n### Docker contexts\n\n```sh\ndocker context list # list contexts\ndocker context use # switch active context\n```\n\n### Customizing the Docker daemon (insecure registries, mirrors)\n\n- v0.3.4 or lower: edit `$HOME/.colima/docker/daemon.json` (generated on first start), then restart.\n- v0.4.0+: `colima start --edit` and add under the `docker:` section:\n\n ```diff\n - docker: {}\n + docker:\n + insecure-registries:\n + - myregistry.com:5000\n + registry-mirrors:\n + - https://my.dockerhub.mirror.something\n ```\n\nRegistry mirrors can also be set at start (repeatable flag), no editing needed:\n\n```sh\ncolima start --registry-mirror https://my.dockerhub.mirror.something\n```\n\n> The host `~/.docker/daemon.json` may also need matching changes for the **client** to honor some\n> values (e.g. registry mirrors). Use `colima template` to bake changes into all new instances.\n\n### Buildx plugin missing\n\n```sh\nbrew install docker-buildx\nmkdir -p ~/.docker/cli-plugins\nln -sfn $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx\ndocker buildx version\n```\n\n## Containerd\n\n```sh\ncolima start --runtime containerd\ncolima nerdctl install # add a `nerdctl` alias to $PATH (recommended)\nnerdctl run hello-world\nnerdctl ps\n```\n\n### Config files (first start with containerd)\n\n| File | Location |\n|---|---|\n| Containerd config | `~/.config/containerd/config.toml` |\n| BuildKit config | `~/.config/buildkit/buildkitd.toml` |\n\nShared across profiles; edit then `colima stop && colima start --runtime containerd`.\n`$XDG_CONFIG_HOME` is respected if set.\n\n**Per-profile override:** place the file at `$HOME/.colima//containerd/config.toml` (or\n`buildkitd.toml`). Resolution order: per-profile override → central (`~/.config/...`) → embedded default.\n\n## Kubernetes\n\n```sh\ncolima start --kubernetes # needs kubectl (brew install kubectl)\nkubectl run caddy --image=caddy\nkubectl get pods\n```\n\nImage registry sharing: Docker runtime — images built/pulled with Docker are available to Kubernetes;\nContainerd runtime — images in the `k8s.io` namespace are available.\n\n## Incus (v0.7.0+)\n\n```sh\ncolima start --runtime incus # needs incus (brew install incus)\nincus launch images:alpine/edge\nincus list\n```\n\nRunning **VMs** on Incus needs an M3 or newer Apple Silicon device. Incus instances aren't reachable\nfrom the host by default (v0.10.0+) — enable network address:\n\n```sh\ncolima stop\ncolima start --network-address\n```\n\n## AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+)\n\nUses the `krunkit` VM type (install [krunkit](https://github.com/containers/krunkit#installation) first).\n\n```sh\ncolima start --runtime docker --vm-type krunkit\ncolima model setup\ncolima model run gemma3\n```\n\nTwo runner backends: **Docker Model Runner** (default — Docker AI Registry + HuggingFace) and\n**Ramalama** (HuggingFace + Ollama). Registry examples:\n\n```sh\ncolima model run gemma3 # Docker AI Registry (default, no prefix)\ncolima model run hf://tinyllama # HuggingFace\ncolima model run ollama://tinyllama --runner ramalama # Ollama (ramalama runner)\n```\n\n`colima model --help` for more.\n\n## How Colima compares\n\n- **vs Lima:** Colima is a higher-level use of Lima — it uses Lima to provide Docker/Containerd/Kubernetes.\n- **vs minikube/Kind/K3d (Kubernetes):** those suit multiple clusters or when you don't need Docker and\n Kubernetes to share images/runtime. Colima with Docker runtime is fully compatible with them.\n- **vs minikube (Docker):** minikube can expose its Docker via `minikube docker-env`, but Kubernetes is\n not optional there, and its free macOS drivers fall short on performance/port-forwarding/volumes for\n Docker-only use.\n\n## Distro / underlying VM\n\n- v0.5.6 and lower: lightweight Alpine image; optional Ubuntu **layer** via `colima start --layer=true`\n (with the layer, `ssh`/`ssh-config` route to the layer; use `--layer=false` to reach the underlying VM).\n- v0.6.0 and newer: Ubuntu is the underlying image; other distros aren't supported.\n"},"items":[{"name":"README.md","path":"skills/README.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/README.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Colima Agent Skill\n\n`SKILL.md` (plus the files in `references/`) is an **Agent Skill** — Markdown with YAML\nfrontmatter that an AI coding assistant loads on demand to give accurate, version-aware Colima\nhelp (install, runtimes, config, troubleshooting, and bootstrap/CI scripting) instead of generic\nDocker advice. It is plain documentation, distilled from this repo's own `docs/`; nothing executes.\n\n## How to use it\n\nThe skill is discovered from the assistant's *skills directory*, where each skill lives in its own\nfolder. Install it as a skill named `colima`:\n\n### Claude Code\n\n```sh\n# user-level (available in every project)\ncp -R skills ~/.claude/skills/colima\n\n# or project-level\ncp -R skills /.claude/skills/colima\n```\n\nStart a new session; the assistant loads the skill automatically when your task involves Colima\n(e.g. *\"my colima docker daemon isn't reachable from IntelliJ\"*, *\"write a CI script that brings\ncolima up with kubernetes\"*).\n\n### Other agents (Cursor, Kimi Code, …)\n\nAny tool that supports the `SKILL.md` format works the same way — copy this folder into that tool's\nskills directory, e.g.:\n\n```sh\ncp -R skills ~/.kimi-code/skills/colima # Kimi Code\n```\n\n…or point the tool's skills path at it directly (Kimi Code: `kimi --skills-dir `).\n\n## What's inside\n\n| File | Contents |\n|---|---|\n| `SKILL.md` | Quick reference + when-to-use (the part the model always sees). |\n| `references/install.md` | Homebrew, MacPorts, Nix, Arch, binary, source. |\n| `references/configuration.md` | Config files, profiles, `COLIMA_HOME`, env into the VM, Lima overrides. |\n| `references/runtimes.md` | Docker, containerd, Kubernetes, Incus, AI models; comparisons. |\n| `references/troubleshooting.md` | Daemon socket errors, `Broken` status, mounts, disk, networking, updates. |\n| `references/automation.md` | Non-interactive patterns for bootstrap / CI / deploy scripts. |\n\nThe content mirrors the canonical docs in [`../docs/`](../docs/); version-gated notes (e.g. `since\nvX.Y.Z`) are preserved, so advice stays correct across the versions users run.\n","isInternal":false,"tokens":536,"sizeBytes":2112},{"name":"automation.md","path":"skills/references/automation.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/references/automation.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Automation: bootstrap & deployment scripts\n\nPatterns for driving Colima **non-interactively** — dev-env bootstrap, CI, deploy scripts. The repo\ndocs are written for interactive use; this page adapts the same commands into script-safe building\nblocks. Pin behavior to a version (`colima version`) since flags vary.\n\n## 1. Wire the rest of the script to Colima's Docker\n\nA script that runs `docker`/`docker compose` after starting Colima must target Colima's daemon. Two ways:\n\n```sh\n# A) point this shell at Colima's socket (v0.4.0+ path)\nexport DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n\n# B) or make Colima the active context (it already sets itself default on start)\ndocker context use colima\n```\n\nDon't hardcode the socket blindly — `colima start` already makes itself the default context, so often no\nexport is needed. Use the explicit `DOCKER_HOST` when the script runs tools that ignore Docker contexts\n(see `troubleshooting.md`). Confirm the path with `colima status`.\n\n## 2. Idempotent start\n\nRe-running the script shouldn't fail if Colima is already up. `colima status` exits non-zero when the\nprofile isn't running:\n\n```sh\n#!/usr/bin/env bash\nset -euo pipefail\n\nPROFILE=\"${COLIMA_PROFILE:-default}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" \\\n --cpu 4 --memory 8 --disk 100 \\\n --runtime docker\nelse\n echo \"colima '$PROFILE' already running\"\nfi\n```\n\nUse a dedicated `--profile` to isolate the script's VM from a developer's `default` one (and to allow\nparallel CI jobs).\n\n## 3. Wait for readiness\n\n`colima start` returns when the VM is provisioned, but in CI it's worth confirming the daemon actually\nanswers before deploying:\n\n```sh\nfor i in $(seq 1 30); do\n if docker info >/dev/null 2>&1; then break; fi\n echo \"waiting for docker... ($i)\"; sleep 2\ndone\ndocker info >/dev/null # final check; fails the script if still not ready\n```\n\n## 4. Non-interactive / CI notes\n\n- **No prompts:** lifecycle commands are non-interactive except destructive ones — use `colima delete --force`.\n- **Foreground (v0.5.6+):** `colima start --foreground` keeps Colima in the foreground; useful under a\n process supervisor (launchd/systemd) or a CI step that owns the lifecycle. Without it, `colima start`\n backgrounds the VM and returns.\n- **Config over flags:** for reproducible environments, commit a `colima.yaml` and apply it with\n `colima start --edit` locally, or bake defaults via `colima template`. See `configuration.md`.\n- **Env into the VM:** `colima start --env KEY=value` (repeatable) or the `env:` config block.\n\n## 5. Teardown\n\n```sh\ncolima stop --profile \"$PROFILE\" # stop, keep the VM\ncolima delete --force --profile \"$PROFILE\" # remove the VM (data on separate disk since v0.9.0 is kept)\ncolima delete --force --data --profile \"$PROFILE\" # also wipe container data\n```\n\n## 6. Bootstrap script skeleton\n\n```sh\n#!/usr/bin/env bash\n# Bring up Colima (docker + kubernetes), make docker target it, deploy.\nset -euo pipefail\nPROFILE=\"${COLIMA_PROFILE:-ci}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" --kubernetes --cpu 4 --memory 8 --disk 60\nfi\n\nexport DOCKER_HOST=\"unix://$HOME/.colima/$PROFILE/docker.sock\" # profile-specific socket\nfor i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done\n\ndocker compose up -d # or: kubectl apply -f k8s/\n# ... deploy / test ...\n\n# teardown (e.g. CI trap):\n# trap 'colima delete --force --profile \"$PROFILE\"' EXIT\n```\n\n> Note the **profile-specific socket** path `$HOME/.colima//docker.sock` — only the `default`\n> profile lives at `.../default/docker.sock`.\n\n## 7. macOS CI (GitHub Actions sketch)\n\nColima needs a macOS runner (nested virtualization). Rough shape:\n\n```yaml\njobs:\n test:\n runs-on: macos-14\n steps:\n - uses: actions/checkout@v4\n - run: brew install colima docker\n - run: colima start --cpu 3 --memory 6 --disk 30\n - run: docker info && docker compose up -d\n # colima is the default context, so docker just works\n```\n\nPin Colima/runner versions for reproducibility; resource flags must fit the runner's limits.\n","isInternal":false,"tokens":1122,"sizeBytes":4203},{"name":"configuration.md","path":"skills/references/configuration.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/references/configuration.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Configuration, profiles & file locations\n\nSource: `docs/FAQ.md`.\n\n## Config file (since v0.4.0)\n\nColima reads a YAML config instead of repeating CLI flags.\n\n```sh\ncolima start --edit # edit + start (one-off)\n```\n\n- Default config: `$HOME/.colima/default/colima.yaml`\n- Other profiles: `$HOME/.colima//colima.yaml`\n- Config location root is `$COLIMA_HOME` (defaults to `$HOME/.colima`).\n\n### Default template for new instances\n\n```sh\ncolima template # edit the default template\n```\n\nTemplate file: `$HOME/.colima/_templates/default.yaml`.\n\n### Choosing the editor\n\nSet `$EDITOR`, or pass `--editor`:\n\n```sh\ncolima start --edit --editor code # one-off\ncolima template --editor code # default config\n```\n\n## File-location environment variables (set on the host)\n\n| Variable | Description |\n|---|---|\n| `COLIMA_HOME` | Colima config directory (default `$HOME/.colima`) |\n| `COLIMA_CACHE_HOME` | Cache directory (host-specific default, see Go `os.UserCacheDir()`) |\n| `COLIMA_PROFILE` | Active profile name (default `default`) |\n| `DOCKER_CONFIG` | Docker client config dir (default `~/.docker`) |\n\n## Passing custom env vars into the VM\n\nConfig file:\n\n```yaml\nenv:\n MY_VAR: value\n```\n\nOr CLI:\n\n```sh\ncolima start --env MY_VAR=value\n# verify inside the VM:\ncolima ssh -- sh -c 'env | grep MY_VAR'\n```\n\n## Autostart\n\n- Foreground mode (since v0.5.6): `colima start --foreground`.\n- Installed via brew: `brew services start colima`.\n\n## Lima overrides (advanced users only)\n\nLima supports `override.yaml` (applied **before** the instance config) and `default.yaml` (applied\n**after**, as fallback defaults).\n\nOverride file: `$HOME/.colima/_lima/_config/override.yaml` (or `$LIMA_HOME/_config/override.yaml` if\n`LIMA_HOME` is set).\n\n> Overriding the **image** is not supported — Colima's image bundles dependencies a custom image would lack.\n\n### Example: provision scripts (run during VM boot)\n\n```yaml\n# $HOME/.colima/_lima/_config/override.yaml\nprovision:\n - mode: system\n script: |\n #!/bin/bash\n set -eux -o pipefail\n apt-get update && apt-get install -y curl\n```\n\nOr directly in `colima.yaml` via `colima start --edit`:\n\n```diff\n- provision: []\n+ provision:\n+ - mode: system\n+ script: |\n+ #!/bin/bash\n+ set -eux -o pipefail\n+ apt-get update && apt-get install -y curl\n```\n\n## Reachable VM IP (macOS only)\n\nDisabled by default (needs root, slower startup). Enable per-start or in config:\n\n```sh\ncolima start --network-address\n```\n\n```diff\nnetwork:\n- address: false\n+ address: true\n```\n\n(For Incus reachability from the host this is required — see `runtimes.md`.)\n","isInternal":false,"tokens":716,"sizeBytes":2659},{"name":"install.md","path":"skills/references/install.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/references/install.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Installing Colima\n\nSource: `docs/INSTALL.md`. Requires macOS 13+ (or Linux). Docker runtime also needs a docker client\n(`brew install docker`).\n\n## Homebrew\n\n```sh\nbrew install colima # stable\nbrew install --HEAD colima # development version\n```\n\n## MacPorts\n\n```sh\nsudo port install colima\n```\n\n## Nix\n\n```sh\nnix-env -i colima # install (stable only)\nnix-shell -p colima # or use only within a nix-shell\n```\n\n## Arch\n\n```sh\nsudo pacman -S qemu-full go docker # dependencies\nyay -S lima-bin colima-bin # Lima + Colima from AUR\n```\n\n## Binary\n\nBinaries ship with every [release](https://github.com/abiosoft/colima/releases).\n\n```sh\n# download binary\ncurl -LO https://github.com/abiosoft/colima/releases/latest/download/colima-$(uname)-$(uname -m)\n\n# install in $PATH\nsudo install colima-$(uname)-$(uname -m) /usr/local/bin/colima\n```\n\n## Building from source\n\nRequires [Go](https://golang.org).\n\n```sh\ngit clone https://github.com/abiosoft/colima\ncd colima\nmake\nsudo make install\n```\n\n## Notes\n\n- Colima requires **macOS 13 or newer**. On older macOS you may be able to build Colima and its\n dependencies ([Lima](https://github.com/lima-vm/lima), [Qemu](https://www.qemu.org/)) from source.\n- Both Intel and Apple Silicon Macs are supported.\n- Updating: `brew upgrade colima`, then `colima delete && colima start` to recreate the VM on the new\n image. The container runtime alone can be updated with `colima update` (v0.7.6+). See\n `troubleshooting.md` → updates.\n","isInternal":false,"tokens":432,"sizeBytes":1513},{"name":"runtimes.md","path":"skills/references/runtimes.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/references/runtimes.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Runtimes: Docker, Containerd, Kubernetes, Incus, AI\n\nSources: `README.md` (usage) + `docs/FAQ.md` (config/details). Runtime is chosen at `colima start`\n(default Docker). **Switching to a different runtime requires re-creating the VM** — a stop/start\nalone does not change it:\n\n```sh\ncolima delete --data && colima start --runtime \n```\n\n## Docker\n\n```sh\ncolima start # docker runtime\ndocker run hello-world\ndocker ps\n```\n\nColima leverages **Docker contexts** and can run alongside Docker Desktop (since v0.3.0); it makes\nitself the default context on startup.\n\n### Socket location (version-gated)\n\n| Version | Docker socket |\n|---|---|\n| v0.3.4 or older | `$HOME/.colima/docker.sock` |\n| v0.4.0 or newer | `$HOME/.colima/default/docker.sock` |\n\nAlso shown by `colima status`.\n\n### Docker contexts\n\n```sh\ndocker context list # list contexts\ndocker context use # switch active context\n```\n\n### Customizing the Docker daemon (insecure registries, mirrors)\n\n- v0.3.4 or lower: edit `$HOME/.colima/docker/daemon.json` (generated on first start), then restart.\n- v0.4.0+: `colima start --edit` and add under the `docker:` section:\n\n ```diff\n - docker: {}\n + docker:\n + insecure-registries:\n + - myregistry.com:5000\n + registry-mirrors:\n + - https://my.dockerhub.mirror.something\n ```\n\nRegistry mirrors can also be set at start (repeatable flag), no editing needed:\n\n```sh\ncolima start --registry-mirror https://my.dockerhub.mirror.something\n```\n\n> The host `~/.docker/daemon.json` may also need matching changes for the **client** to honor some\n> values (e.g. registry mirrors). Use `colima template` to bake changes into all new instances.\n\n### Buildx plugin missing\n\n```sh\nbrew install docker-buildx\nmkdir -p ~/.docker/cli-plugins\nln -sfn $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx\ndocker buildx version\n```\n\n## Containerd\n\n```sh\ncolima start --runtime containerd\ncolima nerdctl install # add a `nerdctl` alias to $PATH (recommended)\nnerdctl run hello-world\nnerdctl ps\n```\n\n### Config files (first start with containerd)\n\n| File | Location |\n|---|---|\n| Containerd config | `~/.config/containerd/config.toml` |\n| BuildKit config | `~/.config/buildkit/buildkitd.toml` |\n\nShared across profiles; edit then `colima stop && colima start --runtime containerd`.\n`$XDG_CONFIG_HOME` is respected if set.\n\n**Per-profile override:** place the file at `$HOME/.colima//containerd/config.toml` (or\n`buildkitd.toml`). Resolution order: per-profile override → central (`~/.config/...`) → embedded default.\n\n## Kubernetes\n\n```sh\ncolima start --kubernetes # needs kubectl (brew install kubectl)\nkubectl run caddy --image=caddy\nkubectl get pods\n```\n\nImage registry sharing: Docker runtime — images built/pulled with Docker are available to Kubernetes;\nContainerd runtime — images in the `k8s.io` namespace are available.\n\n## Incus (v0.7.0+)\n\n```sh\ncolima start --runtime incus # needs incus (brew install incus)\nincus launch images:alpine/edge\nincus list\n```\n\nRunning **VMs** on Incus needs an M3 or newer Apple Silicon device. Incus instances aren't reachable\nfrom the host by default (v0.10.0+) — enable network address:\n\n```sh\ncolima stop\ncolima start --network-address\n```\n\n## AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+)\n\nUses the `krunkit` VM type (install [krunkit](https://github.com/containers/krunkit#installation) first).\n\n```sh\ncolima start --runtime docker --vm-type krunkit\ncolima model setup\ncolima model run gemma3\n```\n\nTwo runner backends: **Docker Model Runner** (default — Docker AI Registry + HuggingFace) and\n**Ramalama** (HuggingFace + Ollama). Registry examples:\n\n```sh\ncolima model run gemma3 # Docker AI Registry (default, no prefix)\ncolima model run hf://tinyllama # HuggingFace\ncolima model run ollama://tinyllama --runner ramalama # Ollama (ramalama runner)\n```\n\n`colima model --help` for more.\n\n## How Colima compares\n\n- **vs Lima:** Colima is a higher-level use of Lima — it uses Lima to provide Docker/Containerd/Kubernetes.\n- **vs minikube/Kind/K3d (Kubernetes):** those suit multiple clusters or when you don't need Docker and\n Kubernetes to share images/runtime. Colima with Docker runtime is fully compatible with them.\n- **vs minikube (Docker):** minikube can expose its Docker via `minikube docker-env`, but Kubernetes is\n not optional there, and its free macOS drivers fall short on performance/port-forwarding/volumes for\n Docker-only use.\n\n## Distro / underlying VM\n\n- v0.5.6 and lower: lightweight Alpine image; optional Ubuntu **layer** via `colima start --layer=true`\n (with the layer, `ssh`/`ssh-config` route to the layer; use `--layer=false` to reach the underlying VM).\n- v0.6.0 and newer: Ubuntu is the underlying image; other distros aren't supported.\n","isInternal":false,"tokens":1300,"sizeBytes":4845},{"name":"troubleshooting.md","path":"skills/references/troubleshooting.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/references/troubleshooting.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Troubleshooting\n\nSource: `docs/FAQ.md`. Many fixes are version-gated — check `colima version` first.\n\n## `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n\nColima uses Docker contexts and sets itself as the default context on start, but some apps ignore\ncontexts. Fix with any of (confirm the socket path first — see socket location in `runtimes.md`):\n\n1. Set an app-specific Docker socket path if supported (e.g. JetBrains IDEs).\n2. Point `DOCKER_HOST` at Colima's socket:\n ```sh\n export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n ```\n3. Link Colima's socket to the default path (**may break other Docker servers**):\n ```sh\n sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock\n ```\n\n## Colima not starting\n\n### Broken status\n\n`colima list` shows `Broken` (often after a macOS restart). Force-stop, then start:\n\n```sh\ncolima stop --force\ncolima start\n```\n\n### `FATA[0000] error starting vm: error at 'starting': exit status 1`\n\nEnable debug logging to investigate:\n\n```sh\ncolima start --verbose\n```\n\nIf the log shows `exiting, status={Running:false Degraded:false Exiting:true ...}`, it's almost always\neither (1) a device without virtualization support, or (2) an x86_64 Homebrew/Colima on an Apple Silicon (M1) device.\n\n### Issues after an upgrade\n\nTest with a separate profile; if it starts cleanly, reset the default profile:\n\n```sh\ncolima start debug # separate profile\n# if that works:\ncolima delete\ncolima start\n```\n\n## Colima cannot access the internet\n\nUsually DNS. Try custom DNS servers and verify from inside the VM:\n\n```sh\ncolima start --dns 8.8.8.8 --dns 1.1.1.1\ncolima ssh -- ping -c4 google.com\n```\n\n## Docker Compose / Buildx `runc ... cgroup ... invalid argument` (v0.5.6 or lower)\n\nWorkaround from v0.5.6: start with `--cgroups-v2`. **Fixed in v0.6.0.**\n\n```sh\ncolima start --cgroups-v2\n```\n\n## Docker bind mount shows empty\n\nBind-mounting a host path **not** under `/Users/$USER` starts the container without error but the\nmountpoint is empty. Mount it on the VM first: edit `$HOME/.colima/default/colima.yaml`, add the path\nto the `mounts` section (examples are in the file), then `colima restart` and re-run the container.\n\n## Mount path with spaces is not supported\n\nPaths with spaces (e.g. `/Volumes/External HD`) aren't supported by the underlying Lima runtime; Colima\nrejects them at startup with a clear error. Workaround: mount a parent dir without spaces, or rename/alias\nthe volume. See [#1471](https://github.com/abiosoft/colima/issues/1471).\n\n## Disk space\n\n### Recover space\n\nFree space in the VM with `docker system prune` or by removing containers. On v0.4.x or lower this\ndoesn't reflect on the host.\n\n- v0.5.0+: unused VM disk space is released on startup — a `colima restart` suffices.\n- v0.5.0+: manual trim:\n ```sh\n colima ssh -- sudo fstrim -a # add -v for verbose\n ```\n\n### Increase disk size (v0.5.3+)\n\nDisk grows on startup from `colima.yaml`:\n\n```diff\n- disk: 150\n+ disk: 250\n```\n\n## Updating\n\n- **Colima itself:** `brew upgrade colima`, then recreate the VM to use the new image:\n ```sh\n colima delete\n colima start\n ```\n Test an upgrade safely on a separate profile: `colima start debug`.\n- **Container runtime only (v0.7.6+):** `colima update` — updates Docker/containerd without updating\n Colima or waiting for a release.\n\n## Accessing the VM directly\n\n```sh\ncolima ssh # interactive shell\ncolima ssh -- uname -a # one-off command\n```\n\n## Deleting container data\n\nSince v0.9.0 container data lives on a separate disk, so `colima delete` preserves it (reinstated on\n`colima start`). To wipe everything including data:\n\n```sh\ncolima delete --data\n```\n","isInternal":false,"tokens":1011,"sizeBytes":3706},{"name":"SKILL.md","path":"skills/SKILL.md","rawUrl":"https://raw.githubusercontent.com/abiosoft/colima/HEAD/skills/SKILL.md","title":"colima","category":"anthropic-skill","format":"markdown","content":"---\nname: colima\ndescription: >-\n Guide to using Colima — container runtimes (Docker, containerd, Kubernetes, Incus) on macOS\n and Linux via lightweight Lima VMs. Use this skill whenever Colima is (or should be) the\n container backend: installing Colima; `colima start/stop/status/delete/ssh`; picking or\n switching a runtime; the `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n error; Docker contexts and socket location; registry mirrors / insecure registries; buildx;\n bind or volume mounts that show up empty in the container; disk space recovery/resize;\n reachable VM IP; GPU / AI model workloads; config files, profiles and `COLIMA_HOME`; or a\n Colima VM that won't start. ALSO use it for **writing scripts that drive Colima** — bootstrap,\n dev-env, deploy, or CI scripts that bring Colima up non-interactively — because the skill has\n the correct flags, profile-specific socket paths, idempotent `colima start` guards, and\n readiness/teardown patterns that hand-written scripts routinely get wrong (e.g. inventing a\n non-existent flag or hardcoding the wrong docker socket). Prefer this over generic Docker\n advice whenever Colima is the daemon. This skill is specifically about **Colima** — not Docker\n Desktop, minikube, Kind, K3d, Rancher Desktop, OrbStack, Podman, or plain `limactl`.\n---\n\n# Colima\n\nColima runs **container runtimes on macOS (and Linux) with minimal setup**. It's a higher-level\nwrapper over [Lima](https://github.com/lima-vm/lima): it boots a small VM and provisions Docker,\ncontainerd, Kubernetes and/or Incus inside it, then wires up the host client so `docker` (etc.)\n\"just works\".\n\n> **Scope:** the canonical source is the repo's own docs (`docs/INSTALL.md`, `docs/FAQ.md`) plus\n> README usage. Behavior is **version-gated** in many places — keep the `vX.Y.Z` notes when\n> advising, since users run a range of versions. Check the user's version with `colima version`.\n\n## Quick start\n\n```sh\nbrew install colima # + docker client if using Docker runtime: brew install docker\ncolima start # boots the VM, Docker runtime by default\ndocker run hello-world # docker client works with no extra setup\n```\n\nFull install options (MacPorts, Nix, Arch, binary, source) → `references/install.md`.\n\n## Core commands\n\n| Command | What it does |\n|---|---|\n| `colima start [profile]` | Create/start the VM. Flags: `--runtime`, `--kubernetes`, `--cpu`, `--memory`, `--disk`, `--edit`, `--env`, `--dns`, `--network-address`, `--vm-type`, `--foreground` |\n| `colima stop [--force]` | Stop the VM. `--force` recovers a `Broken` status |\n| `colima status` | Show running status (incl. Docker socket path) |\n| `colima list` | List profiles and their status/arch/cpus/mem/disk/runtime |\n| `colima restart` | Stop + start (needed after editing mounts/config) |\n| `colima delete [--data]` | Delete the VM. `--data` also deletes container data (since v0.9.0 data lives on a separate disk) |\n| `colima ssh [-- ]` | Shell into the VM, or run one command |\n| `colima start --edit` | Start while editing the YAML config (since v0.4.0) |\n| `colima template` | Edit the default config template for new instances |\n| `colima update` | Update the container runtime in place (since v0.7.6) |\n| `colima nerdctl ...` | nerdctl wrapper for the containerd runtime |\n| `colima model ...` | Set up / run AI models (GPU, krunkit; since v0.10.0) |\n| `colima version` | Print the version (use it before applying version-gated advice) |\n\nProfiles isolate independent VMs: `colima start work` operates on the `work` profile; default is `default`.\n`colima --help` / `colima start --help` list everything.\n\n## Runtimes — chosen at `start`\n\nDefault is Docker. **Switching the runtime requires re-creating the VM** — a stop/start alone\ndoes not change it: `colima delete --data && colima start --runtime `.\n\n- **Docker** (default): `colima start` → `docker ...` works directly. Needs the docker client (`brew install docker`).\n- **Containerd**: `colima start --runtime containerd` → use `colima nerdctl ...` (run `colima nerdctl install` to add a `nerdctl` alias to `$PATH`).\n- **Kubernetes**: `colima start --kubernetes` (needs `kubectl`). Shares images with the chosen container runtime.\n- **Incus** (v0.7.0+): `colima start --runtime incus` → `incus ...`.\n- **AI models / GPU** (v0.10.0+, Apple Silicon, macOS 13+): `colima start --runtime docker --vm-type krunkit` then `colima model run gemma3`.\n\nPer-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → `references/runtimes.md`.\n\n> **Registry mirror** (common task): `colima start --registry-mirror ` (repeatable) or `--edit` →\n> add under `docker.registry-mirrors`. For the **client** to honor mirrors, the host\n> `~/.docker/daemon.json` may also need the same entries. Details → `references/runtimes.md`.\n\n## Customizing the VM\n\nDefaults: **2 CPUs, 2 GiB memory, 100 GiB disk**. Customize via flags or the config file.\n\n```sh\ncolima start --cpu 4 --memory 8 --disk 100 # at create time\ncolima stop && colima start --cpu 4 --memory 8 # change an existing VM (disk can only grow)\ncolima start --vm-type=vz --vz-rosetta # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+)\n```\n\nConfig files, profiles, `COLIMA_HOME`, passing env into the VM, Lima overrides → `references/configuration.md`.\n\n**Writing a bootstrap / CI / deploy script?** See `references/automation.md` for non-interactive patterns:\nidempotent start (`colima status` guard), readiness wait (`docker info` loop), `DOCKER_HOST` wiring so the\nrest of the script targets Colima, `--foreground` for supervisors, teardown, and a GitHub Actions sketch.\n\n## Common gotchas (quick)\n\n- **`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`** — an app isn't using Colima's\n Docker context. Point it at Colima's socket (`export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"`)\n or relink the socket. Details + socket location by version → `references/troubleshooting.md`.\n- **`Broken` status** (e.g. after a macOS restart): `colima stop --force`, then `colima start`.\n- **Docker bind mount shows empty** — the host path must be under `/Users/$USER`, or add it to the `mounts`\n section of the config and `colima restart`. Paths with spaces are unsupported.\n- **Won't start / fatal error** — re-run with `--verbose`; common causes are no virtualization support or an\n x86_64 Homebrew/Colima on Apple Silicon. See `references/troubleshooting.md`.\n\nFull troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade\nissues, deleting data) → `references/troubleshooting.md`.\n\n## References\n\n- `references/install.md` — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).\n- `references/configuration.md` — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.\n- `references/runtimes.md` — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.\n- `references/troubleshooting.md` — startup failures, networking, mounts, disk, updates, deleting data.\n- `references/automation.md` — non-interactive patterns for bootstrap / CI / deploy scripts.\n","frontmatter":{"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`."},"isInternal":false,"tokens":1910,"sizeBytes":7291}],"systemPromptSnippet":"\n\n# Colima Agent Skill\n\n`SKILL.md` (plus the files in `references/`) is an **Agent Skill** — Markdown with YAML\nfrontmatter that an AI coding assistant loads on demand to give accurate, version-aware Colima\nhelp (install, runtimes, config, troubleshooting, and bootstrap/CI scripting) instead of generic\nDocker advice. It is plain documentation, distilled from this repo's own `docs/`; nothing executes.\n\n## How to use it\n\nThe skill is discovered from the assistant's *skills directory*, where each skill lives in its own\nfolder. Install it as a skill named `colima`:\n\n### Claude Code\n\n```sh\n# user-level (available in every project)\ncp -R skills ~/.claude/skills/colima\n\n# or project-level\ncp -R skills /.claude/skills/colima\n```\n\nStart a new session; the assistant loads the skill automatically when your task involves Colima\n(e.g. *\"my colima docker daemon isn't reachable from IntelliJ\"*, *\"write a CI script that brings\ncolima up with kubernetes\"*).\n\n### Other agents (Cursor, Kimi Code, …)\n\nAny tool that supports the `SKILL.md` format works the same way — copy this folder into that tool's\nskills directory, e.g.:\n\n```sh\ncp -R skills ~/.kimi-code/skills/colima # Kimi Code\n```\n\n…or point the tool's skills path at it directly (Kimi Code: `kimi --skills-dir `).\n\n## What's inside\n\n| File | Contents |\n|---|---|\n| `SKILL.md` | Quick reference + when-to-use (the part the model always sees). |\n| `references/install.md` | Homebrew, MacPorts, Nix, Arch, binary, source. |\n| `references/configuration.md` | Config files, profiles, `COLIMA_HOME`, env into the VM, Lima overrides. |\n| `references/runtimes.md` | Docker, containerd, Kubernetes, Incus, AI models; comparisons. |\n| `references/troubleshooting.md` | Daemon socket errors, `Broken` status, mounts, disk, networking, updates. |\n| `references/automation.md` | Non-interactive patterns for bootstrap / CI / deploy scripts. |\n\nThe content mirrors the canonical docs in [`../docs/`](../docs/); version-gated notes (e.g. `since\nvX.Y.Z`) are preserved, so advice stays correct across the versions users run.\n\n\n# Automation: bootstrap & deployment scripts\n\nPatterns for driving Colima **non-interactively** — dev-env bootstrap, CI, deploy scripts. The repo\ndocs are written for interactive use; this page adapts the same commands into script-safe building\nblocks. Pin behavior to a version (`colima version`) since flags vary.\n\n## 1. Wire the rest of the script to Colima's Docker\n\nA script that runs `docker`/`docker compose` after starting Colima must target Colima's daemon. Two ways:\n\n```sh\n# A) point this shell at Colima's socket (v0.4.0+ path)\nexport DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n\n# B) or make Colima the active context (it already sets itself default on start)\ndocker context use colima\n```\n\nDon't hardcode the socket blindly — `colima start` already makes itself the default context, so often no\nexport is needed. Use the explicit `DOCKER_HOST` when the script runs tools that ignore Docker contexts\n(see `troubleshooting.md`). Confirm the path with `colima status`.\n\n## 2. Idempotent start\n\nRe-running the script shouldn't fail if Colima is already up. `colima status` exits non-zero when the\nprofile isn't running:\n\n```sh\n#!/usr/bin/env bash\nset -euo pipefail\n\nPROFILE=\"${COLIMA_PROFILE:-default}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" \\\n --cpu 4 --memory 8 --disk 100 \\\n --runtime docker\nelse\n echo \"colima '$PROFILE' already running\"\nfi\n```\n\nUse a dedicated `--profile` to isolate the script's VM from a developer's `default` one (and to allow\nparallel CI jobs).\n\n## 3. Wait for readiness\n\n`colima start` returns when the VM is provisioned, but in CI it's worth confirming the daemon actually\nanswers before deploying:\n\n```sh\nfor i in $(seq 1 30); do\n if docker info >/dev/null 2>&1; then break; fi\n echo \"waiting for docker... ($i)\"; sleep 2\ndone\ndocker info >/dev/null # final check; fails the script if still not ready\n```\n\n## 4. Non-interactive / CI notes\n\n- **No prompts:** lifecycle commands are non-interactive except destructive ones — use `colima delete --force`.\n- **Foreground (v0.5.6+):** `colima start --foreground` keeps Colima in the foreground; useful under a\n process supervisor (launchd/systemd) or a CI step that owns the lifecycle. Without it, `colima start`\n backgrounds the VM and returns.\n- **Config over flags:** for reproducible environments, commit a `colima.yaml` and apply it with\n `colima start --edit` locally, or bake defaults via `colima template`. See `configuration.md`.\n- **Env into the VM:** `colima start --env KEY=value` (repeatable) or the `env:` config block.\n\n## 5. Teardown\n\n```sh\ncolima stop --profile \"$PROFILE\" # stop, keep the VM\ncolima delete --force --profile \"$PROFILE\" # remove the VM (data on separate disk since v0.9.0 is kept)\ncolima delete --force --data --profile \"$PROFILE\" # also wipe container data\n```\n\n## 6. Bootstrap script skeleton\n\n```sh\n#!/usr/bin/env bash\n# Bring up Colima (docker + kubernetes), make docker target it, deploy.\nset -euo pipefail\nPROFILE=\"${COLIMA_PROFILE:-ci}\"\n\nif ! colima status --profile \"$PROFILE\" >/dev/null 2>&1; then\n colima start --profile \"$PROFILE\" --kubernetes --cpu 4 --memory 8 --disk 60\nfi\n\nexport DOCKER_HOST=\"unix://$HOME/.colima/$PROFILE/docker.sock\" # profile-specific socket\nfor i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done\n\ndocker compose up -d # or: kubectl apply -f k8s/\n# ... deploy / test ...\n\n# teardown (e.g. CI trap):\n# trap 'colima delete --force --profile \"$PROFILE\"' EXIT\n```\n\n> Note the **profile-specific socket** path `$HOME/.colima//docker.sock` — only the `default`\n> profile lives at `.../default/docker.sock`.\n\n## 7. macOS CI (GitHub Actions sketch)\n\nColima needs a macOS runner (nested virtualization). Rough shape:\n\n```yaml\njobs:\n test:\n runs-on: macos-14\n steps:\n - uses: actions/checkout@v4\n - run: brew install colima docker\n - run: colima start --cpu 3 --memory 6 --disk 30\n - run: docker info && docker compose up -d\n # colima is the default context, so docker just works\n```\n\nPin Colima/runner versions for reproducibility; resource flags must fit the runner's limits.\n\n\n# Configuration, profiles & file locations\n\nSource: `docs/FAQ.md`.\n\n## Config file (since v0.4.0)\n\nColima reads a YAML config instead of repeating CLI flags.\n\n```sh\ncolima start --edit # edit + start (one-off)\n```\n\n- Default config: `$HOME/.colima/default/colima.yaml`\n- Other profiles: `$HOME/.colima//colima.yaml`\n- Config location root is `$COLIMA_HOME` (defaults to `$HOME/.colima`).\n\n### Default template for new instances\n\n```sh\ncolima template # edit the default template\n```\n\nTemplate file: `$HOME/.colima/_templates/default.yaml`.\n\n### Choosing the editor\n\nSet `$EDITOR`, or pass `--editor`:\n\n```sh\ncolima start --edit --editor code # one-off\ncolima template --editor code # default config\n```\n\n## File-location environment variables (set on the host)\n\n| Variable | Description |\n|---|---|\n| `COLIMA_HOME` | Colima config directory (default `$HOME/.colima`) |\n| `COLIMA_CACHE_HOME` | Cache directory (host-specific default, see Go `os.UserCacheDir()`) |\n| `COLIMA_PROFILE` | Active profile name (default `default`) |\n| `DOCKER_CONFIG` | Docker client config dir (default `~/.docker`) |\n\n## Passing custom env vars into the VM\n\nConfig file:\n\n```yaml\nenv:\n MY_VAR: value\n```\n\nOr CLI:\n\n```sh\ncolima start --env MY_VAR=value\n# verify inside the VM:\ncolima ssh -- sh -c 'env | grep MY_VAR'\n```\n\n## Autostart\n\n- Foreground mode (since v0.5.6): `colima start --foreground`.\n- Installed via brew: `brew services start colima`.\n\n## Lima overrides (advanced users only)\n\nLima supports `override.yaml` (applied **before** the instance config) and `default.yaml` (applied\n**after**, as fallback defaults).\n\nOverride file: `$HOME/.colima/_lima/_config/override.yaml` (or `$LIMA_HOME/_config/override.yaml` if\n`LIMA_HOME` is set).\n\n> Overriding the **image** is not supported — Colima's image bundles dependencies a custom image would lack.\n\n### Example: provision scripts (run during VM boot)\n\n```yaml\n# $HOME/.colima/_lima/_config/override.yaml\nprovision:\n - mode: system\n script: |\n #!/bin/bash\n set -eux -o pipefail\n apt-get update && apt-get install -y curl\n```\n\nOr directly in `colima.yaml` via `colima start --edit`:\n\n```diff\n- provision: []\n+ provision:\n+ - mode: system\n+ script: |\n+ #!/bin/bash\n+ set -eux -o pipefail\n+ apt-get update && apt-get install -y curl\n```\n\n## Reachable VM IP (macOS only)\n\nDisabled by default (needs root, slower startup). Enable per-start or in config:\n\n```sh\ncolima start --network-address\n```\n\n```diff\nnetwork:\n- address: false\n+ address: true\n```\n\n(For Incus reachability from the host this is required — see `runtimes.md`.)\n\n\n# Installing Colima\n\nSource: `docs/INSTALL.md`. Requires macOS 13+ (or Linux). Docker runtime also needs a docker client\n(`brew install docker`).\n\n## Homebrew\n\n```sh\nbrew install colima # stable\nbrew install --HEAD colima # development version\n```\n\n## MacPorts\n\n```sh\nsudo port install colima\n```\n\n## Nix\n\n```sh\nnix-env -i colima # install (stable only)\nnix-shell -p colima # or use only within a nix-shell\n```\n\n## Arch\n\n```sh\nsudo pacman -S qemu-full go docker # dependencies\nyay -S lima-bin colima-bin # Lima + Colima from AUR\n```\n\n## Binary\n\nBinaries ship with every [release](https://github.com/abiosoft/colima/releases).\n\n```sh\n# download binary\ncurl -LO https://github.com/abiosoft/colima/releases/latest/download/colima-$(uname)-$(uname -m)\n\n# install in $PATH\nsudo install colima-$(uname)-$(uname -m) /usr/local/bin/colima\n```\n\n## Building from source\n\nRequires [Go](https://golang.org).\n\n```sh\ngit clone https://github.com/abiosoft/colima\ncd colima\nmake\nsudo make install\n```\n\n## Notes\n\n- Colima requires **macOS 13 or newer**. On older macOS you may be able to build Colima and its\n dependencies ([Lima](https://github.com/lima-vm/lima), [Qemu](https://www.qemu.org/)) from source.\n- Both Intel and Apple Silicon Macs are supported.\n- Updating: `brew upgrade colima`, then `colima delete && colima start` to recreate the VM on the new\n image. The container runtime alone can be updated with `colima update` (v0.7.6+). See\n `troubleshooting.md` → updates.\n\n\n# Runtimes: Docker, Containerd, Kubernetes, Incus, AI\n\nSources: `README.md` (usage) + `docs/FAQ.md` (config/details). Runtime is chosen at `colima start`\n(default Docker). **Switching to a different runtime requires re-creating the VM** — a stop/start\nalone does not change it:\n\n```sh\ncolima delete --data && colima start --runtime \n```\n\n## Docker\n\n```sh\ncolima start # docker runtime\ndocker run hello-world\ndocker ps\n```\n\nColima leverages **Docker contexts** and can run alongside Docker Desktop (since v0.3.0); it makes\nitself the default context on startup.\n\n### Socket location (version-gated)\n\n| Version | Docker socket |\n|---|---|\n| v0.3.4 or older | `$HOME/.colima/docker.sock` |\n| v0.4.0 or newer | `$HOME/.colima/default/docker.sock` |\n\nAlso shown by `colima status`.\n\n### Docker contexts\n\n```sh\ndocker context list # list contexts\ndocker context use # switch active context\n```\n\n### Customizing the Docker daemon (insecure registries, mirrors)\n\n- v0.3.4 or lower: edit `$HOME/.colima/docker/daemon.json` (generated on first start), then restart.\n- v0.4.0+: `colima start --edit` and add under the `docker:` section:\n\n ```diff\n - docker: {}\n + docker:\n + insecure-registries:\n + - myregistry.com:5000\n + registry-mirrors:\n + - https://my.dockerhub.mirror.something\n ```\n\nRegistry mirrors can also be set at start (repeatable flag), no editing needed:\n\n```sh\ncolima start --registry-mirror https://my.dockerhub.mirror.something\n```\n\n> The host `~/.docker/daemon.json` may also need matching changes for the **client** to honor some\n> values (e.g. registry mirrors). Use `colima template` to bake changes into all new instances.\n\n### Buildx plugin missing\n\n```sh\nbrew install docker-buildx\nmkdir -p ~/.docker/cli-plugins\nln -sfn $(which docker-buildx) ~/.docker/cli-plugins/docker-buildx\ndocker buildx version\n```\n\n## Containerd\n\n```sh\ncolima start --runtime containerd\ncolima nerdctl install # add a `nerdctl` alias to $PATH (recommended)\nnerdctl run hello-world\nnerdctl ps\n```\n\n### Config files (first start with containerd)\n\n| File | Location |\n|---|---|\n| Containerd config | `~/.config/containerd/config.toml` |\n| BuildKit config | `~/.config/buildkit/buildkitd.toml` |\n\nShared across profiles; edit then `colima stop && colima start --runtime containerd`.\n`$XDG_CONFIG_HOME` is respected if set.\n\n**Per-profile override:** place the file at `$HOME/.colima//containerd/config.toml` (or\n`buildkitd.toml`). Resolution order: per-profile override → central (`~/.config/...`) → embedded default.\n\n## Kubernetes\n\n```sh\ncolima start --kubernetes # needs kubectl (brew install kubectl)\nkubectl run caddy --image=caddy\nkubectl get pods\n```\n\nImage registry sharing: Docker runtime — images built/pulled with Docker are available to Kubernetes;\nContainerd runtime — images in the `k8s.io` namespace are available.\n\n## Incus (v0.7.0+)\n\n```sh\ncolima start --runtime incus # needs incus (brew install incus)\nincus launch images:alpine/edge\nincus list\n```\n\nRunning **VMs** on Incus needs an M3 or newer Apple Silicon device. Incus instances aren't reachable\nfrom the host by default (v0.10.0+) — enable network address:\n\n```sh\ncolima stop\ncolima start --network-address\n```\n\n## AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+)\n\nUses the `krunkit` VM type (install [krunkit](https://github.com/containers/krunkit#installation) first).\n\n```sh\ncolima start --runtime docker --vm-type krunkit\ncolima model setup\ncolima model run gemma3\n```\n\nTwo runner backends: **Docker Model Runner** (default — Docker AI Registry + HuggingFace) and\n**Ramalama** (HuggingFace + Ollama). Registry examples:\n\n```sh\ncolima model run gemma3 # Docker AI Registry (default, no prefix)\ncolima model run hf://tinyllama # HuggingFace\ncolima model run ollama://tinyllama --runner ramalama # Ollama (ramalama runner)\n```\n\n`colima model --help` for more.\n\n## How Colima compares\n\n- **vs Lima:** Colima is a higher-level use of Lima — it uses Lima to provide Docker/Containerd/Kubernetes.\n- **vs minikube/Kind/K3d (Kubernetes):** those suit multiple clusters or when you don't need Docker and\n Kubernetes to share images/runtime. Colima with Docker runtime is fully compatible with them.\n- **vs minikube (Docker):** minikube can expose its Docker via `minikube docker-env`, but Kubernetes is\n not optional there, and its free macOS drivers fall short on performance/port-forwarding/volumes for\n Docker-only use.\n\n## Distro / underlying VM\n\n- v0.5.6 and lower: lightweight Alpine image; optional Ubuntu **layer** via `colima start --layer=true`\n (with the layer, `ssh`/`ssh-config` route to the layer; use `--layer=false` to reach the underlying VM).\n- v0.6.0 and newer: Ubuntu is the underlying image; other distros aren't supported.\n\n\n# Troubleshooting\n\nSource: `docs/FAQ.md`. Many fixes are version-gated — check `colima version` first.\n\n## `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n\nColima uses Docker contexts and sets itself as the default context on start, but some apps ignore\ncontexts. Fix with any of (confirm the socket path first — see socket location in `runtimes.md`):\n\n1. Set an app-specific Docker socket path if supported (e.g. JetBrains IDEs).\n2. Point `DOCKER_HOST` at Colima's socket:\n ```sh\n export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"\n ```\n3. Link Colima's socket to the default path (**may break other Docker servers**):\n ```sh\n sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock\n ```\n\n## Colima not starting\n\n### Broken status\n\n`colima list` shows `Broken` (often after a macOS restart). Force-stop, then start:\n\n```sh\ncolima stop --force\ncolima start\n```\n\n### `FATA[0000] error starting vm: error at 'starting': exit status 1`\n\nEnable debug logging to investigate:\n\n```sh\ncolima start --verbose\n```\n\nIf the log shows `exiting, status={Running:false Degraded:false Exiting:true ...}`, it's almost always\neither (1) a device without virtualization support, or (2) an x86_64 Homebrew/Colima on an Apple Silicon (M1) device.\n\n### Issues after an upgrade\n\nTest with a separate profile; if it starts cleanly, reset the default profile:\n\n```sh\ncolima start debug # separate profile\n# if that works:\ncolima delete\ncolima start\n```\n\n## Colima cannot access the internet\n\nUsually DNS. Try custom DNS servers and verify from inside the VM:\n\n```sh\ncolima start --dns 8.8.8.8 --dns 1.1.1.1\ncolima ssh -- ping -c4 google.com\n```\n\n## Docker Compose / Buildx `runc ... cgroup ... invalid argument` (v0.5.6 or lower)\n\nWorkaround from v0.5.6: start with `--cgroups-v2`. **Fixed in v0.6.0.**\n\n```sh\ncolima start --cgroups-v2\n```\n\n## Docker bind mount shows empty\n\nBind-mounting a host path **not** under `/Users/$USER` starts the container without error but the\nmountpoint is empty. Mount it on the VM first: edit `$HOME/.colima/default/colima.yaml`, add the path\nto the `mounts` section (examples are in the file), then `colima restart` and re-run the container.\n\n## Mount path with spaces is not supported\n\nPaths with spaces (e.g. `/Volumes/External HD`) aren't supported by the underlying Lima runtime; Colima\nrejects them at startup with a clear error. Workaround: mount a parent dir without spaces, or rename/alias\nthe volume. See [#1471](https://github.com/abiosoft/colima/issues/1471).\n\n## Disk space\n\n### Recover space\n\nFree space in the VM with `docker system prune` or by removing containers. On v0.4.x or lower this\ndoesn't reflect on the host.\n\n- v0.5.0+: unused VM disk space is released on startup — a `colima restart` suffices.\n- v0.5.0+: manual trim:\n ```sh\n colima ssh -- sudo fstrim -a # add -v for verbose\n ```\n\n### Increase disk size (v0.5.3+)\n\nDisk grows on startup from `colima.yaml`:\n\n```diff\n- disk: 150\n+ disk: 250\n```\n\n## Updating\n\n- **Colima itself:** `brew upgrade colima`, then recreate the VM to use the new image:\n ```sh\n colima delete\n colima start\n ```\n Test an upgrade safely on a separate profile: `colima start debug`.\n- **Container runtime only (v0.7.6+):** `colima update` — updates Docker/containerd without updating\n Colima or waiting for a release.\n\n## Accessing the VM directly\n\n```sh\ncolima ssh # interactive shell\ncolima ssh -- uname -a # one-off command\n```\n\n## Deleting container data\n\nSince v0.9.0 container data lives on a separate disk, so `colima delete` preserves it (reinstated on\n`colima start`). To wipe everything including data:\n\n```sh\ncolima delete --data\n```\n\n\n---\nname: colima\ndescription: >-\n Guide to using Colima — container runtimes (Docker, containerd, Kubernetes, Incus) on macOS\n and Linux via lightweight Lima VMs. Use this skill whenever Colima is (or should be) the\n container backend: installing Colima; `colima start/stop/status/delete/ssh`; picking or\n switching a runtime; the `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`\n error; Docker contexts and socket location; registry mirrors / insecure registries; buildx;\n bind or volume mounts that show up empty in the container; disk space recovery/resize;\n reachable VM IP; GPU / AI model workloads; config files, profiles and `COLIMA_HOME`; or a\n Colima VM that won't start. ALSO use it for **writing scripts that drive Colima** — bootstrap,\n dev-env, deploy, or CI scripts that bring Colima up non-interactively — because the skill has\n the correct flags, profile-specific socket paths, idempotent `colima start` guards, and\n readiness/teardown patterns that hand-written scripts routinely get wrong (e.g. inventing a\n non-existent flag or hardcoding the wrong docker socket). Prefer this over generic Docker\n advice whenever Colima is the daemon. This skill is specifically about **Colima** — not Docker\n Desktop, minikube, Kind, K3d, Rancher Desktop, OrbStack, Podman, or plain `limactl`.\n---\n\n# Colima\n\nColima runs **container runtimes on macOS (and Linux) with minimal setup**. It's a higher-level\nwrapper over [Lima](https://github.com/lima-vm/lima): it boots a small VM and provisions Docker,\ncontainerd, Kubernetes and/or Incus inside it, then wires up the host client so `docker` (etc.)\n\"just works\".\n\n> **Scope:** the canonical source is the repo's own docs (`docs/INSTALL.md`, `docs/FAQ.md`) plus\n> README usage. Behavior is **version-gated** in many places — keep the `vX.Y.Z` notes when\n> advising, since users run a range of versions. Check the user's version with `colima version`.\n\n## Quick start\n\n```sh\nbrew install colima # + docker client if using Docker runtime: brew install docker\ncolima start # boots the VM, Docker runtime by default\ndocker run hello-world # docker client works with no extra setup\n```\n\nFull install options (MacPorts, Nix, Arch, binary, source) → `references/install.md`.\n\n## Core commands\n\n| Command | What it does |\n|---|---|\n| `colima start [profile]` | Create/start the VM. Flags: `--runtime`, `--kubernetes`, `--cpu`, `--memory`, `--disk`, `--edit`, `--env`, `--dns`, `--network-address`, `--vm-type`, `--foreground` |\n| `colima stop [--force]` | Stop the VM. `--force` recovers a `Broken` status |\n| `colima status` | Show running status (incl. Docker socket path) |\n| `colima list` | List profiles and their status/arch/cpus/mem/disk/runtime |\n| `colima restart` | Stop + start (needed after editing mounts/config) |\n| `colima delete [--data]` | Delete the VM. `--data` also deletes container data (since v0.9.0 data lives on a separate disk) |\n| `colima ssh [-- ]` | Shell into the VM, or run one command |\n| `colima start --edit` | Start while editing the YAML config (since v0.4.0) |\n| `colima template` | Edit the default config template for new instances |\n| `colima update` | Update the container runtime in place (since v0.7.6) |\n| `colima nerdctl ...` | nerdctl wrapper for the containerd runtime |\n| `colima model ...` | Set up / run AI models (GPU, krunkit; since v0.10.0) |\n| `colima version` | Print the version (use it before applying version-gated advice) |\n\nProfiles isolate independent VMs: `colima start work` operates on the `work` profile; default is `default`.\n`colima --help` / `colima start --help` list everything.\n\n## Runtimes — chosen at `start`\n\nDefault is Docker. **Switching the runtime requires re-creating the VM** — a stop/start alone\ndoes not change it: `colima delete --data && colima start --runtime `.\n\n- **Docker** (default): `colima start` → `docker ...` works directly. Needs the docker client (`brew install docker`).\n- **Containerd**: `colima start --runtime containerd` → use `colima nerdctl ...` (run `colima nerdctl install` to add a `nerdctl` alias to `$PATH`).\n- **Kubernetes**: `colima start --kubernetes` (needs `kubectl`). Shares images with the chosen container runtime.\n- **Incus** (v0.7.0+): `colima start --runtime incus` → `incus ...`.\n- **AI models / GPU** (v0.10.0+, Apple Silicon, macOS 13+): `colima start --runtime docker --vm-type krunkit` then `colima model run gemma3`.\n\nPer-runtime config, socket location, registry mirrors, buildx, nerdctl, AI model registries → `references/runtimes.md`.\n\n> **Registry mirror** (common task): `colima start --registry-mirror ` (repeatable) or `--edit` →\n> add under `docker.registry-mirrors`. For the **client** to honor mirrors, the host\n> `~/.docker/daemon.json` may also need the same entries. Details → `references/runtimes.md`.\n\n## Customizing the VM\n\nDefaults: **2 CPUs, 2 GiB memory, 100 GiB disk**. Customize via flags or the config file.\n\n```sh\ncolima start --cpu 4 --memory 8 --disk 100 # at create time\ncolima stop && colima start --cpu 4 --memory 8 # change an existing VM (disk can only grow)\ncolima start --vm-type=vz --vz-rosetta # Rosetta 2 (v0.5.3+, Apple Silicon, macOS 13+)\n```\n\nConfig files, profiles, `COLIMA_HOME`, passing env into the VM, Lima overrides → `references/configuration.md`.\n\n**Writing a bootstrap / CI / deploy script?** See `references/automation.md` for non-interactive patterns:\nidempotent start (`colima status` guard), readiness wait (`docker info` loop), `DOCKER_HOST` wiring so the\nrest of the script targets Colima, `--foreground` for supervisors, teardown, and a GitHub Actions sketch.\n\n## Common gotchas (quick)\n\n- **`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`** — an app isn't using Colima's\n Docker context. Point it at Colima's socket (`export DOCKER_HOST=\"unix://$HOME/.colima/default/docker.sock\"`)\n or relink the socket. Details + socket location by version → `references/troubleshooting.md`.\n- **`Broken` status** (e.g. after a macOS restart): `colima stop --force`, then `colima start`.\n- **Docker bind mount shows empty** — the host path must be under `/Users/$USER`, or add it to the `mounts`\n section of the config and `colima restart`. Paths with spaces are unsupported.\n- **Won't start / fatal error** — re-run with `--verbose`; common causes are no virtualization support or an\n x86_64 Homebrew/Colima on Apple Silicon. See `references/troubleshooting.md`.\n\nFull troubleshooting (no internet/DNS, runc/cgroups error, disk recovery & resize, reachable IP, post-upgrade\nissues, deleting data) → `references/troubleshooting.md`.\n\n## References\n\n- `references/install.md` — all install methods (Homebrew, MacPorts, Nix, Arch, binary, source).\n- `references/configuration.md` — config file & profiles, file locations & env vars, custom VM env, Lima overrides, autostart.\n- `references/runtimes.md` — Docker (socket/contexts/registries/buildx), Containerd, Kubernetes, Incus, AI models; comparisons to Lima/minikube/Kind/K3d.\n- `references/troubleshooting.md` — startup failures, networking, mounts, disk, updates, deleting data.\n- `references/automation.md` — non-interactive patterns for bootstrap / CI / deploy scripts.\n"}