working-with-colima

Manage Colima lifecycles and Docker contexts on macOS.

10|4|Updated Nov 12, 2025

Search Tags:#troubleshooting #docker #macos #contexts #colima #container-runtime

Ready to run

npx skills add https://github.com/technicalpickles/pickled-claude-plugins --skill working-with-colima

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: working-with-colima
Source: https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/dev-tools/skills/working-with-colima
Command: npx skills add https://github.com/technicalpickles/pickled-claude-plugins --skill working-with-colima

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Provides Colima lifecycle management, context handling, and troubleshooting guidance for macOS/container environments.

Core Features & Use Cases

Colima startup/shutdown/status; manage profiles
Docker context integration and socket path handling
Troubleshooting Colima issues (Broken status, DNS, network)
SSH agent forwarding for Docker builds

Quick Start

Start a Colima profile and verify Docker: colima start; docker version; colima status -p default --json | jq -r .docker_socket; If needed, export DOCKER_HOST to the socket.

Frequently Asked Questions about working-with-colima

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I fix Docker daemon connection failures on macOS with Colima?▼

Docker daemon connection failures on macOS typically stem from Colima not running or misconfigured Docker contexts. Start Colima with `colima start`, verify the connection with `docker version`, then check the socket path using `colima status --json`. If needed, export `DOCKER_HOST` to the socket path returned by that command to establish the connection.

What is Colima and why do I need it for Docker on macOS?▼

Colima is a container runtime for macOS that manages the Docker daemon lifecycle. macOS cannot run Linux containers natively, so Colima provisions and manages a lightweight VM to host Docker, eliminating the need for Docker Desktop and providing direct control over startup, shutdown, and resource allocation.

How do I manage multiple Colima profiles and switch Docker contexts?▼

Create and manage Colima profiles using `colima start -p [profile-name]` and `colima stop -p [profile-name]`. Switch Docker contexts between profiles using `docker context ls` to list available contexts and `docker context use [context-name]` to activate the desired one, ensuring you're working with the correct container runtime.

Can I use SSH agent forwarding with Colima for Docker builds?▼

Yes, Colima supports SSH agent forwarding for Docker builds on macOS. Configure agent forwarding during Colima startup or in profile settings to allow `docker build` commands to access SSH keys for private repository access during the build process.

Why is my Colima status showing as broken and how do I troubleshoot it?▼

Broken Colima status typically indicates lifecycle, DNS, or network issues. Run `colima status --json` to inspect detailed state, verify network connectivity, check DNS configuration, and review logs. Restart the Colima profile with `colima stop` followed by `colima start` to resolve most transient issues.

Do I need to manually set DOCKER_HOST when using Colima?▼

Manual `DOCKER_HOST` configuration is usually unnecessary if Colima and Docker contexts are properly initialized. However, if Docker commands fail to locate the daemon, you can explicitly set `DOCKER_HOST` to the socket path obtained from `colima status --json` to force connection to the correct Colima instance.