Claude Code for Colima Docker — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Colima as your Docker runtime on macOS — the lightweight alternative to Docker Desktop that runs containers in a Lima VM. Colima provides Docker and containerd runtimes without the Docker Desktop license cost. Claude Code can work with Docker commands, but it assumes Docker Desktop features and configuration paths that differ in Colima.

What Claude Code Gets Wrong By Default

  1. References Docker Desktop settings UI. Claude says “open Docker Desktop preferences to change…” — Colima has no GUI. Configuration is done via colima start --cpu 4 --memory 8 command flags or ~/.colima/default/colima.yaml.

  2. Uses Docker Desktop-specific features. Claude enables “Use Docker Compose V2” in Docker Desktop settings. Colima installs Docker Compose as a CLI plugin — it is available by default after brew install docker-compose.

  3. Assumes the Docker socket at the default path. Claude uses /var/run/docker.sock which is Docker Desktop’s path. Colima uses ~/.colima/default/docker.sock — set DOCKER_HOST accordingly.

  4. Enables Kubernetes through Docker Desktop. Claude toggles Kubernetes in Docker Desktop settings. Colima has its own Kubernetes support: colima start --kubernetes which runs k3s in the VM.

The CLAUDE.md Configuration

# Colima Docker Runtime

## Container Runtime
- Docker runtime: Colima (NOT Docker Desktop)
- VM: Lima-based, configurable CPU/memory
- Socket: ~/.colima/default/docker.sock
- Kubernetes: colima start --kubernetes (k3s)

## Colima Rules
- Start: colima start --cpu 4 --memory 8 --disk 60
- Stop: colima stop
- Status: colima status
- Docker socket: DOCKER_HOST=unix://~/.colima/default/docker.sock
- Config: ~/.colima/default/colima.yaml
- No GUI — all config via CLI or YAML
- Docker commands work normally after colima start
- Volume mounts: host paths accessible via Lima mount

## Conventions
- Set DOCKER_HOST in shell config for Colima socket
- Start Colima before running Docker commands
- Resource limits: configure at VM level, not per-container
- Kubernetes: use colima start --kubernetes for k3s
- File sharing: default mounts ~ (configurable in colima.yaml)
- Rosetta: colima start --arch aarch64 --vm-type vz for Apple Silicon

Workflow Example

You want to set up a development environment with Colima and Docker Compose. Prompt Claude Code:

“Configure Colima for this project with 4 CPUs, 8GB RAM, and 60GB disk. Set up the Docker socket environment variable, verify Docker works, and start the project’s Docker Compose services.”

Claude Code should configure Colima start parameters, export DOCKER_HOST in the shell config, verify with docker info, and run docker compose up -d — noting that no Docker Desktop installation is needed.

Common Pitfalls

  1. Docker socket not configured. Claude runs docker ps after Colima start but gets “Cannot connect to the Docker daemon.” Set export DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock in your shell config.

  2. Volume mount performance. Claude mounts large directories without considering I/O. Colima’s default file sharing can be slow on macOS. Use --vm-type vz with --mount-type virtiofs for better performance on Apple Silicon.

  3. Forgetting to start Colima. Claude assumes Docker is always available. Unlike Docker Desktop which auto-starts, Colima must be started manually with colima start. Add it to your shell startup or use colima start in project scripts.