DOCSEARCHbyAlgolia
Submit Docs

Colima

repository·main·Indexed 12 days ago

https://github.com/abiosoft/colima

Container runtimes for macOS and Linux with minimal setup. Colima leverages Lima to provide lightweight Linux virtual machines supporting Docker, Containerd, and Incus, with additional features like Kubernetes integration, GPU acceleration for AI workloads (v0.10.0+), and automatic port forwarding.

Tokens
22.4K
Snippets
127
Records
141
Agent score
93%

What's inside Colima

  1. Overview of Colima Agent Skill contents

    main

    The Colima Agent Skill provides structured documentation to help AI models provide accurate advice on installation, configuration, runtimes, and troubleshooting. The skill is composed of the following files:

    FileContents
    SKILL.mdQuick reference and usage guidance (primary context for the model).
    references/install.mdInstallation instructions for Homebrew, MacPorts, Nix, Arch, binaries, and source.
    references/configuration.mdDetails on config files, profiles, COLIMA_HOME, environment variables into the VM, and Lima overrides.
    references/runtimes.mdInformation on Docker, containerd, Kubernetes, Incus, and AI models, including comparisons.
    references/troubleshooting.mdSolutions for daemon socket errors, Broken status, mounts, disk, networking, and updates.
    references/automation.mdNon-interactive patterns for bootstrap, CI, and deployment scripts.

    All content is distilled from the official Colima documentation and preserves version-gated notes (e.g., since vX.Y.Z) to ensure accuracy across different Colima versions.

  2. Use Lima overrides for advanced configuration

    main

    Colima is built on Lima, which allows for advanced overrides via override.yaml. These are applied before the instance configuration.

    • Override file location: $HOME/.colima/_lima/_config/override.yaml (or $LIMA_HOME/_config/override.yaml).
    • Note: You cannot override the image via this method, as Colima's image bundles specific dependencies.

    Provisioning scripts

    You can run scripts during VM boot by adding a provision section to the override file or the colima.yaml file. Use mode: system for system-level tasks.

    # $HOME/.colima/_lima/_config/override.yaml
provision:
  - mode: system
    script: |
      #!/bin/bash
      set -eux -o pipefail
      apt-get update && apt-get install -y curl

  3. Colima System Requirements and Compatibility

    main

    Requirements

    • macOS: Version 13 or newer is required. For older macOS versions, you may need to build Colima and its dependencies (Lima, Qemu) from source.
    • Linux: Supported.
    • Docker Runtime: Requires a docker client installed (e.g., brew install docker).

    Hardware Support

    • Both Intel and Apple Silicon Macs are supported.

  4. Configure Colima runtimes

    main

    Colima supports multiple runtimes. Note: Switching the runtime requires re-creating the VM. A simple stop/start will not change the runtime. To switch, use: colima delete --data && colima start --runtime <new>.

    Supported Runtimes

    • Docker (default): Works directly with the docker client. Requires brew install docker on macOS.
    • Containerd: Use colima start --runtime containerd. Access via colima nerdctl ... (run colima nerdctl install to add a nerdctl alias to your $PATH).
    • Kubernetes: Use colima start --kubernetes. Requires kubectl. It shares images with the chosen container runtime.
    • Incus (v0.7.0+): Use colima start --runtime incus to use the incus CLI.
    • AI models / GPU (v0.10.0+, Apple Silicon, macOS 13+): Use colima start --runtime docker --vm-type krunkit followed by colima model run <model_name>.

    Registry Mirrors

    To use a registry mirror, use the flag during start:

    colima start --registry-mirror <url>

    Alternatively, use colima start --edit and add the mirror under docker.registry-mirrors in the YAML config. For the host client to honor these, you may also need to add them to your host's ~/.docker/daemon.json.

    # Example: Switching to containerd
colima delete --data && colima start --runtime containerd

# Example: Running an AI model on Apple Silicon
colima start --runtime docker --vm-type krunkit
colima model run gemma3

  5. Configure Colima for non-interactive/CI environments

    main

    When automating Colima, keep these behaviors in mind:

    • Non-interactive commands: Most lifecycle commands are non-interactive. For destructive actions, use the --force flag (e.g., colima delete --force).
    • Foreground mode: Use colima start --foreground (available in v0.5.6+) to keep Colima in the foreground. This is useful when running under a process supervisor like systemd or launchd, or in CI steps that need to own the lifecycle.
    • Environment Variables: Pass variables into the VM using colima start --env KEY=value or via the env: block in a configuration file.
    • Reproducibility: Use colima start --edit to apply a colima.yaml configuration or use colima template to bake in defaults.

  6. Install Colima via Homebrew

    main

    You can install Colima using Homebrew. Use the standard command for the stable version, or the --HEAD flag to install the development version.

    # Stable Version
brew install colima

# Development Version
brew install --HEAD colima

  7. Customize VM resources and types

    main

    Colima defaults to 2 CPUs, 2 GiB memory, and 100 GiB disk. You can customize these at creation time or modify existing VMs (though disk size can only grow).

    Resource Allocation

    # Set resources at creation time
colima start --cpu 4 --memory 8 --disk 100

# Change resources for an existing VM
colima stop && colima start --cpu 4 --memory 8

    Virtualization Types

    On Apple Silicon (macOS 13+), you can use Rosetta 2 for improved performance:

    colima start --vm-type=vz --vz-rosetta
    colima start --cpu 4 --memory 8 --disk 100

  8. Customizing the Docker daemon

    main

    You can configure the Docker daemon for settings like insecure-registries and registry-mirrors.

    For Colima v0.4.0 and newer

    Use the --edit flag to open the configuration file. Add your settings under the docker: section:

    - docker: {}
+ docker:
+   insecure-registries:
+     - myregistry.com:5000
+   registry-mirrors:
+     - https://my.dockerhub.mirror.something

    Using CLI flags for mirrors

    Alternatively, you can set registry mirrors directly at startup using a repeatable flag without editing files:

    colima start --registry-mirror https://my.dockerhub.mirror.something

    For Colima v0.3.4 or older

    Edit the generated $HOME/.colima/docker/daemon.json file and restart Colima.

    colima start --edit
# OR
colima start --registry-mirror https://my.dockerhub.mirror.something

  10. Update Colima and Container Runtimes

    main

    Updating Colima

    To update the Colima application itself (e.g., via Homebrew), you must recreate the VM to use the new image:

    brew upgrade colima
colima delete
colima start

    Tip: Test upgrades safely using colima start debug first.

    Updating Container Runtimes only (v0.7.6+)

    If you only need to update Docker or containerd without updating the Colima application, use the update command:

    colima update
    brew upgrade colima
colima delete
colima start

colima update

  11. Use Colima with an AI coding assistant

    main

    Colima provides 'Agent Skills' (Markdown files) that AI coding assistants (like Claude Code, Cursor, or Kimi Code) can load to provide accurate, version-aware guidance.

    To install the skills, copy the skills/ directory into your assistant's skills directory. For example, for Claude:

    cp -R skills ~/.claude/skills/colima

  12. Start Colima with Incus runtime

    main

    Requires Colima v0.7.0+. You must have the incus client installed (e.g., brew install incus).

    Note: Running virtual machines on Incus is only supported on m3 or newer Apple Silicon devices.

    colima start --runtime incus
incus launch images:alpine/edge
incus list