What is Colima, and when should I use this skill?

Colima provides Docker and Containerd runtimes on macOS by running a Linux VM and exposing Docker via per-profile contexts.

How do I switch between profiles/contexts?

Each profile maps to a Docker context (default -> colima, work -> colima-work). Use commands like docker context use colima-work or export DOCKER_CONTEXT=colima-work to direct commands.

Is Colima for Linux environments or Kubernetes?

No. Colima is designed for macOS to run Docker runtimes via a Linux VM and manage multiple contexts; it is not a Linux host tool or a Kubernetes-specific setup.

colima

npx machina-cli add skill technicalpickles/pickled-claude-plugins/colima --openclaw

Files (1)

SKILL.md

2.8 KB

Colima

Overview

Colima provides container runtimes (Docker, Containerd) on macOS with minimal setup. It runs a Linux VM and exposes Docker via contexts.

Use this skill when:

Docker commands fail ("Cannot connect to Docker daemon")
Starting/stopping container runtime on macOS
Managing multiple Docker profiles/contexts
Troubleshooting container environment issues
Need SSH agent forwarding for Docker builds

Not for: Docker Compose, Kubernetes clusters, or Linux environments.

Quick Reference

Operation	Command
Start	`colima start` or `colima start <profile>`
Start with SSH agent	`colima start <profile> -s`
Stop	`colima stop` or `colima stop --force`
Status	`colima status -p <profile>`
List profiles	`colima list`
SSH into VM	`colima ssh` or `colima ssh -- <cmd>`
SSH with chained commands	`colima ssh -- bash -c "cmd1 && cmd2"`
Get socket path	`colima status -p <profile> --json \| jq -r .docker_socket`

Docker Context Basics

Colima creates Docker contexts per profile:

Profile default → context colima
Profile work → context colima-work

# Switch context (global - affects all terminals)
docker context use colima-work

# Override per-session
export DOCKER_CONTEXT=colima-work

# Override per-command
docker --context colima-work ps

For details, see references/docker-contexts.md.

Common Issues

Docker daemon not connecting?

colima status - is it running?
docker context list - right context selected?
See references/troubleshooting.md for more

Need more VM resources?

colima stop && colima start --cpu 4 --memory 8

"Broken" status after restart?

colima stop --force && colima start

References

references/ssh-commands.md - SSH command syntax, chaining, escaping
references/docker-contexts.md - Context switching, DOCKER_HOST, socket paths
references/profile-management.md - Creating, configuring, deleting profiles
references/troubleshooting.md - Common issues and solutions
references/common-options.md - Flags, VM types, resource configuration

Upstream Documentation

Local copies of official Colima docs (from github.com/abiosoft/colima):

references/colima-upstream/README.md - Official README with features and usage
references/colima-upstream/FAQ.md - Official FAQ and troubleshooting
references/colima-upstream/INSTALL.md - Installation options

Source

git clone https://github.com/technicalpickles/pickled-claude-plugins/blob/main/plugins/dev-tools/skills/colima/SKILL.mdView on GitHub

Overview

Colima provides Docker and Containerd runtimes on macOS by running a Linux VM. It exposes Docker through per-profile contexts, enabling you to start, stop, switch between multiple environments, and troubleshoot container setups. It even supports SSH agent forwarding for Docker builds.

How This Skill Works

Colima runs a Linux VM on macOS and presents Docker via per-profile contexts (default -> colima, work -> colima-work). You manage lifecycles with colima start/stop, connect via colima ssh, and direct Docker commands to the correct runtime using docker context commands or environment variables. The skill links to references for troubleshooting and profile management to guide advanced usage.

When to Use It

Docker commands fail with a connectivity error on macOS (Cannot connect to Docker daemon).
You need to start or stop the container runtime on macOS.
You manage multiple Docker profiles or contexts and want isolation between them.
You are troubleshooting container environment issues on macOS.
You require SSH agent forwarding for Docker builds.

Quick Start

Step 1: colima list
Step 2: colima start or colima start <profile> -s
Step 3: Switch context (e.g., docker context use colima-work) and run a test (docker ps)

Best Practices

Use per-profile contexts to keep environments isolated (default colima, work colima-work).
Regularly verify the active context with docker context ls and colima status -p <profile>.
When running heavy workloads, adjust VM resources at startup (e.g., --cpu, --memory).
Switch contexts with docker context use <profile> and verify with docker context ls before running commands.
Consult references/troubleshooting.md for common issues and solutions before escalating problems.

Example Use Cases

Start the default Colima profile and run docker ps to verify the daemon is reachable.
Switch to the 'work' profile and run containers in that isolated context.
Start Colima with SSH agent forwarding using colima start default -s for builds requiring SSH keys.
Increase VM resources when builds require more RAM/CPU: colima stop && colima start --cpu 4 --memory 8.
SSH into the Colima VM to inspect the Docker environment directly (colima ssh) and run docker commands inside.

Frequently Asked Questions

Add this skill to your agents