If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/k3d-io/k3d shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 23+ active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live k3d-io/k3d repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/k3d-io/k3d.

What it runs against: a local clone of k3d-io/k3d — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in k3d-io/k3d | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of k3d-io/k3d. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/k3d-io/k3d.git
#   cd k3d
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of k3d-io/k3d and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "k3d-io/k3d(\\.git)?\\b" \\
  && ok "origin remote is k3d-io/k3d" \\
  || miss "origin remote is not k3d-io/k3d (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 50 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~20d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/k3d-io/k3d"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

k3d is a lightweight wrapper that runs CNCF's k3s (minimal Kubernetes) inside Docker containers, allowing developers to spin up multi-node Kubernetes clusters on a single machine without needing full Kubernetes infrastructure. It solves the problem of having a fast, resource-efficient local Kubernetes development environment that mirrors production behavior while staying under 100MB. Modular CLI-driven architecture: cmd/ directory contains command handlers (cluster, image, kubeconfig, config, debug) wrapping a core library at the root package level. GitHub Actions workflows show the build pipeline. Makefile orchestrates builds. No monorepo; single focused codebase with clear separation between CLI commands and underlying functionality.

Cloud-native developers and DevOps engineers who need fast local Kubernetes clusters for testing, CI/CD pipeline development, and experimenting with Kubernetes configurations without the overhead of full K8s or minikube. Contributors are primarily community-driven maintainers working on Docker orchestration tooling.

Production-ready and actively maintained. The project has 28 contributors, clear versioning history (v5.0.0 released September 2021), comprehensive GitHub Actions CI/CD workflows (test-matrix.yaml, release.yaml, test-install-osmatrix.yaml), and well-documented breaking changes across major versions. Latest releases show active development with clear documentation at k3d.io.

Moderate risk: depends heavily on Docker API stability (requires Docker ≥ v20.10.5 per issue #807) and containerd internals; single upstream dependency on k3s-io/k3s for Kubernetes distribution. Community-driven rather than officially supported by Rancher (noted in README), and breaking changes between major versions require attention during upgrades. Monitor k3s release cycles for compatibility impacts.

Active maintenance with documented workflows for AUR releases (aur-release.yml, aur-prerelease.yml), sponsor management (sponsors-readme.yaml), and cross-platform testing (test-install-osmatrix.yaml). The codebase includes planning documentation (.planning/codebase/) covering architecture, integrations, and testing conventions, indicating ongoing architectural review and contributor onboarding.

git clone https://github.com/k3d-io/k3d && cd k3d && make build (uses Makefile; Go 1.24.4+ required per go.mod). See Makefile targets for dev tasks. Requires Docker daemon running locally.

Daily commands: make build (outputs binary), then k3d cluster create <name> to spin up a cluster. make test runs the test suite. Makefile contains all standard dev targets. Binary is statically linked; runs on Linux/macOS/Windows with Docker.

• cmd/cluster/clusterCreate.go: Primary entry point for cluster creation logic; most user-facing feature and likely place for enhancements
• .planning/codebase/ARCHITECTURE.md: Documents the design philosophy, layering strategy, and decision rationale for the entire codebase
• .golangci.yml: Defines linting rules and code quality standards enforced across the project
• Makefile: Build automation; entry point for all dev tasks (test, build, lint, release)
• .github/workflows/test-matrix.yaml: CI pipeline definition showing which Go versions, platforms, and Docker versions are tested
• .planning/codebase/CONVENTIONS.md: Coding standards and style conventions specific to this project

CLI commands live in cmd/<subsystem>/<subsystem>Command.go (e.g., cmd/cluster/clusterCreate.go for cluster creation logic). Core types and functions are at the package root. Start with cmd/cluster/ for cluster operations, cmd/image/ for image handling, or cmd/kubeconfig/ for kubeconfig management. Tests follow Go conventions (see .planning/codebase/TESTING.md for test patterns).

Docker daemon must be running and accessible via the standard Docker socket (/var/run/docker.sock on Linux or Docker Desktop socket on macOS/Windows). Requires Docker ≥ v20.10.5 with runc ≥ v1.0.0-rc93 (see issue #807). The codebase uses Go modules (v5 suffix in import paths); always use 'go mod tidy' before committing. Breaking changes are introduced in major versions without backward compatibility; check CHANGELOG.md before assuming API stability.

• Container Networking and Host Routing — k3d must bridge Docker container networking with host networking so kubectl can reach the cluster API; understanding how docker networks, port mapping, and DNS resolution work is critical for debugging connectivity issues
• Kubernetes Kubeconfig and Authentication — cmd/kubeconfig/kubeconfigGet.go reads and merges kubeconfigs from k3d clusters; understanding kubeconfig structure (contexts, clusters, users, credentials) is essential for that subsystem
• Docker API Client SDK — k3d orchestrates container lifecycle via the Docker Go SDK (docker/docker dependency); all cluster creation/deletion logic depends on the Docker API contract
• Cobra Command Framework — All CLI commands in cmd/* are built on spf13/cobra; understanding Cobra's command routing, flag parsing, and subcommand structure is required to add new commands or modify existing ones
• Multi-Node Cluster Orchestration — k3d creates multi-node clusters where each node is a separate Docker container; the cluster creation logic must handle inter-container networking, shared storage (mounts), and cluster initialization scripts
• Docker Image Management — cmd/image/imageImport.go handles loading images into running k3d clusters via Docker/containerd; understanding image layers, registries, and container runtime image stores is needed for this feature
• Config Serialization and Versioning — cmd/config/configMigrate.go manages schema evolution across k3d versions; the codebase must handle backward-compatible config loading and migration between major versions without breaking existing clusters

• k3s-io/k3s — Upstream Kubernetes distribution that k3d wraps; understanding k3s version constraints and breaking changes is essential
• rancher/rancher — Companion Rancher product that k3d clusters often integrate with for testing multi-cluster scenarios
• kubernetes/kubernetes — Core Kubernetes project; k3d is optimized for testing K8s workloads locally before pushing to production K8s
• docker/cli — Docker CLI client library that k3d depends on for container orchestration commands
• containerd/containerd — Container runtime that k3s uses internally; understanding containerd is helpful for debugging k3d cluster issues

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for kubeconfig merge functionality

The cmd/kubeconfig/kubeconfigMerge.go file exists but there's no evidence of dedicated integration tests in the file structure. Given k3d's core purpose of managing Kubernetes clusters, kubeconfig merging is a critical user-facing feature. Adding tests would ensure the merge logic handles edge cases (duplicate contexts, conflicting cluster definitions, user credential preservation) correctly across different kubeconfig formats.

• [ ] Create pkg/kubeconfig/merge_test.go with unit tests for merge logic
• [ ] Add integration test in .github/workflows/test-matrix.yaml that validates kubeconfig merging across multiple cluster scenarios
• [ ] Test edge cases: empty kubeconfigs, conflicting context names, overwriting existing contexts
• [ ] Document test scenarios in .planning/codebase/TESTING.md

Add GitHub Action workflow for linting and validating CLI documentation generation

The repo has docgen module (go.mod shows docgen dependency) and generates CLI documentation, but there's no CI workflow validating that docs stay in sync with command definitions. The existing workflows (test-matrix.yaml, release.yaml) don't cover documentation validation. This prevents drift between actual CLI behavior and shipped documentation.

• [ ] Create .github/workflows/docs-validation.yaml that runs 'make docs' or equivalent
• [ ] Add step to validate generated markdown matches committed docs in repo
• [ ] Ensure workflow fails if CLI changes aren't reflected in documentation
• [ ] Add job that checks for missing command documentation (cmd/**/*.go files)

Add unit tests for node management command builders (nodeCreate, nodeEdit, nodeDelete)

The cmd/node/ directory has multiple command files (nodeCreate.go, nodeEdit.go, nodeDelete.go) but no visible corresponding test files in the structure. These commands are core to k3d's functionality. Unit tests should validate flag parsing, validation logic, and error handling without requiring Docker/cluster setup.

• [ ] Create cmd/node/nodeCreate_test.go with tests for flag parsing (labels, env vars, memory limits, etc.)
• [ ] Create cmd/node/nodeEdit_test.go with tests for patch validation and node selector logic
• [ ] Create cmd/node/nodeDelete_test.go with tests for force-delete and dependency checking
• [ ] Add test helper functions in cmd/util/testing.go for mock node command setup

• Add integration tests for the cmd/image/imageImport.go flow covering Docker image import edge cases (repo suggests testing framework exists in .planning/codebase/TESTING.md but imageImport lacks dedicated test coverage)
• Document the config migration logic in cmd/config/configMigrate.go with inline examples showing v4→v5 config transformations (planning docs mention config management but end-user examples are sparse)
• Extend cmd/kubeconfig/kubeconfigGet.go to support output formats (YAML, JSON, plain) with tests, following patterns in existing commands

The k3d codebase shows moderate security posture with notable concerns around outdated dependencies (

• High · Outdated Go Dependencies with Known Vulnerabilities — docgen/go.mod. The docgen/go.mod file specifies multiple outdated dependencies that likely contain known CVEs. Notable examples include: docker v20.10.24 (multiple CVEs), containerd v1.6.18 (end-of-life), go-ansiterm v0.0.0-20210617225240 (2021 version). These dependencies should be updated to their latest patched versions. Fix: Run 'go get -u' to update dependencies to latest versions. Review CVE databases for: docker/docker, containerd/containerd, Microsoft/hcsshim. Consider implementing dependabot or similar automated dependency scanning.
• High · Docker Base Image Version Not Pinned to Specific Digest — Dockerfile (lines with golang:1.24.4 and docker:$DOCKER_VERSION-dind). The Dockerfile uses 'golang:1.24.4' and 'docker:$DOCKER_VERSION-dind' without pinning to specific image digests. While versions are specified, image digests should be used to prevent image drift and ensure reproducible builds. An attacker could potentially compromise the image registry. Fix: Pin Docker base images to specific SHA256 digests: 'FROM golang:1.24.4@sha256:...' and 'FROM docker:$DOCKER_VERSION-dind@sha256:...'. Implement image signature verification in CI/CD pipelines.
• Medium · Build Arguments Not Validated in Dockerfile — Dockerfile (ARG directives). The Dockerfile accepts ARG values (GIT_TAG_OVERRIDE, OS, ARCH) without validation or sanitization. Malicious build-time argument injection could lead to unexpected behavior or security issues during the build process. Fix: Validate build arguments: verify GIT_TAG_OVERRIDE matches expected git tag format, validate OS and ARCH against whitelist of supported values. Add explicit checks or use build-time security scanning.
• Medium · Potential Privilege Escalation in Docker Image — Dockerfile (dind stage and builder COPY command). The dind stage from 'docker:$DOCKER_VERSION-dind' runs Docker-in-Docker which inherently requires elevated privileges. Combined with the 'COPY . .' command that copies all repository contents into the builder, there's potential for privilege escalation if the build context contains malicious files. Fix: Use .dockerignore to exclude sensitive files. Implement multi-stage builds with minimal layers. Consider using rootless Docker or alternative container runtimes. Scan build context before building.
• Medium · Missing Security Scanning in CI/CD Workflows — .github/workflows/ (particularly release.yaml and test-matrix.yaml). Review of GitHub workflows (.github/workflows/*.yaml) suggests no explicit container image vulnerability scanning (Trivy, Grype, etc.) before release. The release.yaml and test-matrix.yaml workflows should include security scanning steps. Fix: Add container image scanning steps using tools like Trivy or Grype. Implement SBOM generation (SPDX/CycloneDX format). Block releases if high/critical vulnerabilities are detected.
• Low · Incomplete Dependency Analysis in go.mod — docgen/go.mod (truncated content). The provided go.mod snippet is truncated ('github.com/magicona' is cut off), making complete dependency analysis impossible. This truncation could hide vulnerable dependencies. Fix: Provide complete go.mod file. Run 'go mod graph' and 'go mod verify' to audit all transitive dependencies. Use 'go list -json -m all' to generate complete dependency list for analysis.
• Low · Build Process May Copy Unnecessary Files — Dockerfile (builder stage). The builder stage uses 'COPY . .' which copies the entire repository including .git, test files, and documentation. While not a direct security risk, this increases image size and potential attack surface. Fix: Use .dockerignore to exclude unnecessary files (test fixtures, documentation, .git, .github). Implement explicit COPY statements for required files only. Reduces image bloat and potential exposure.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.