Claude Code for Colima Docker (2026)

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.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Common Questions

How do I get started with claude code for colima docker?

Begin with the setup instructions in this guide. Install the required dependencies, configure your environment, and test with a small project before scaling to your full codebase.

What are the prerequisites?

You need a working development environment with Node.js or Python installed. Familiarity with the command line and basic Git operations is helpful. No advanced AI knowledge is required.

Can I use this with my existing development workflow?

Yes. These techniques integrate with standard development tools and CI/CD pipelines. Start by adding them to a single project and expand once you have verified the benefits.

Where can I find more advanced techniques?

Explore the related resources below for deeper coverage. The Claude Code documentation and community forums also provide advanced patterns and real-world case studies.