Kurtosis docker-debug

Debug Kurtosis running on local Docker. Inspect engine, API container, and service logs. Diagnose container crashes, port conflicts, and networking issues. Use when kurtosis commands fail or services aren't reachable on Docker.

install

source · Clone the upstream repo

git clone https://github.com/kurtosis-tech/kurtosis

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/kurtosis-tech/kurtosis "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/docker-debug" ~/.claude/skills/kurtosis-tech-kurtosis-docker-debug && rm -rf "$T"

manifest: skills/docker-debug/SKILL.md

Docker Debug

Diagnose and fix issues with Kurtosis running on a local Docker engine.

Quick triage

# Check engine is running
kurtosis engine status

# List all kurtosis containers
docker ps -a --filter "label=app.kubernetes.io/managed-by=kurtosis" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# If no label filter works, grep for kurtosis
docker ps -a | grep kurtosis

Engine issues

Engine won't start

# Check if old engine is still running
docker ps -a | grep kurtosis-engine

# Check engine logs
docker logs $(docker ps -aq --filter "name=kurtosis-engine") 2>&1 | tail -50

# Nuclear option: stop and remove all kurtosis containers
kurtosis engine stop
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
kurtosis engine start

Engine version mismatch

# Check CLI version
kurtosis version

# Check running engine version
kurtosis engine status

# Force restart with matching version
kurtosis engine restart

Enclave / API container issues

The API container (core/APIC) runs inside each enclave and manages services.

# List enclaves
kurtosis enclave ls

# Find the APIC container for an enclave
docker ps -a | grep "kurtosis-api"

# View APIC logs (most useful for debugging enclave creation failures)
docker logs $(docker ps -aq --filter "name=kurtosis-api") 2>&1 | tail -100

Service debugging

# List services in an enclave
kurtosis enclave inspect <enclave-name>

# View service logs
kurtosis service logs <enclave-name> <service-name>

# Follow logs in real time
kurtosis service logs <enclave-name> <service-name> -f

# Shell into a running service
kurtosis service shell <enclave-name> <service-name>

# Execute a command in a service
kurtosis service exec <enclave-name> <service-name> -- <command>

Port and networking issues

# Check mapped ports for a service
kurtosis enclave inspect <enclave-name>

# Verify port is actually listening inside the container
kurtosis service exec <enclave-name> <service-name> -- netstat -tlnp

# Test connectivity between services (from inside a service)
kurtosis service exec <enclave-name> <service-name> -- wget -qO- http://<other-service>:<port>/endpoint

File artifacts

# List file artifacts in an enclave
kurtosis enclave inspect <enclave-name>

# Download a file artifact for inspection
kurtosis files download <enclave-name> <artifact-name> /tmp/artifact-output

Common problems

Symptom	Likely cause	Fix
`engine not running`	Engine crashed or was stopped	`kurtosis engine start`
Port conflict on start	Old container holding the port	`docker ps -a \| grep kurtosis \| awk '{print $1}' \| xargs docker rm -f`
Service unreachable	Wrong port or service not ready	Check `kurtosis enclave inspect` for mapped ports
`image not found`	Image not pulled or tag wrong	Check image name in Starlark, try `docker pull <image>`
Enclave creation hangs	APIC crash or image pull issue	Check APIC logs: `docker logs` on the kurtosis-api container

Cleanup

# Remove a specific enclave
kurtosis enclave rm <enclave-name>

# Remove all enclaves and clean up
kurtosis clean -a

# Full nuclear clean (if kurtosis clean fails)
docker ps -a | grep kurtosis | awk '{print $1}' | xargs -r docker rm -f
docker network ls | grep kurtosis | awk '{print $1}' | xargs -r docker network rm
kurtosis engine start