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/telepresenceio/telepresence 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 1d ago
• 9 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits

_{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 telepresenceio/telepresence repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/telepresenceio/telepresence.

What it runs against: a local clone of telepresenceio/telepresence — 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 telepresenceio/telepresence | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch release/v2 exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of telepresenceio/telepresence. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/telepresenceio/telepresence.git
#   cd telepresence
#
# 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 telepresenceio/telepresence and re-run."
  exit 2
fi

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

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

# 3. Default branch
git rev-parse --verify release/v2 >/dev/null 2>&1 \\
  && ok "default branch release/v2 exists" \\
  || miss "default branch release/v2 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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/telepresenceio/telepresence"
  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).

Telepresence is a CNCF project that bridges local development environments to remote Kubernetes/OpenShift clusters by creating a virtual network tunnel, allowing developers to run services locally while accessing cluster resources without container build/push/deploy cycles. It intercepts traffic destined for cluster workloads and routes it to local machines, enabling real-time debugging and development against live cluster infrastructure. Monorepo structure with build-aux/ containing CI/build tooling (Dockerfile variants for client, traffic manager, route controller), cmd/ containing CLI entry points (cobraparser handles CLI parsing), main Go modules for networking and Kubernetes integration, and GitHub Actions workflows in .github/workflows/ orchestrating releases and testing. Traffic manager runs as cluster-side component while client runs locally.

Kubernetes platform engineers and backend developers who need fast local iteration against remote clusters; DevOps teams managing multi-service environments who want to test changes without full deployment pipelines; contributors to cloud-native projects who need to verify code against actual cluster configurations.

Production-ready and actively maintained. The project is CNCF-backed with comprehensive CI/CD pipelines (.github/workflows/ includes unit tests, dependency scanning, image scanning, and release automation), extensive documentation structure, and active GitHub workflows for releases and dependency management. The large Go codebase (2.5M LOC) and multiple Dockerfile variants indicate mature, multi-platform support.

Low-to-moderate risk for a CNCF project. Direct dependency on Docker SDK and OpenContainers specs (see go.mod) means vulnerability in those libraries propagates; the admission_controller_tls component (build-aux/) suggests critical TLS handling that requires careful testing. No indication of single-maintainer bottleneck (MAINTAINERS.md exists), but the complexity of network-level traffic interception means any breaking changes could severely impact users running production workloads.

Active development with recent CI/CD enhancements (go-dependency-submission.yaml, image-scan.yaml workflows), route controller as separate component (Dockerfile.routecontroller), and Windows support (Dockerfile.winbuild, build-aux/pkg-installer for macOS pkg distribution). CHANGELOG.yml tracks recent changes; release.yaml and release-teleroute.yaml suggest ongoing versioning and component-specific releases.

git clone https://github.com/telepresenceio/telepresence.git
cd telepresence
make dev  # or check Makefile for target commands
# Verify dependencies from build-aux/main.mk and .github/actions/install-dependencies/action.yaml

Daily commands: From Makefile and build-aux/main.mk: make dev starts local development; GitHub Actions workflows show build steps via go build with version generation (build-aux/genversion/main.go). Platform-specific: Dockerfile.client for local client, Dockerfile.traffic for cluster-side traffic manager. See build-aux/docker/images/ for container build details.

• build-aux/main.mk: Primary build orchestration for all platforms and components; defines targets for Go compilation, Docker image building, and release artifacts
• .github/workflows/release.yaml: Defines the automated release pipeline including version tagging, image building, and distribution to multiple platforms
• build-aux/docker/images/Dockerfile.traffic: Builds the critical cluster-side traffic manager component that intercepts and routes Kubernetes traffic to local machines
• build-aux/admission_controller_tls/main.go: Implements secure TLS-based communication between cluster components and local client; security-critical for authenticated interception
• cmd/cobraparser/v2: CLI argument parsing entry point; where user-facing commands are configured and routed
• .golangci.yml: Go linter configuration enforcing code quality standards across the 2.5M LOC codebase
• CLAUDE.md: Developer-facing build instructions and architecture overview; likely contains setup steps and internal patterns

CLI commands: modify cmd/cobraparser/v2 and flag handling; networking/traffic interception: look in main Go modules (likely cmd/ subdirectories); cluster components: edit build-aux/docker/images/Dockerfile.traffic and corresponding Go code; admission control: build-aux/admission_controller_tls/main.go; Windows support: cmd/ and build-aux/pkg-installer/. Tests via .github/workflows/unit_tests.yaml pattern.

Kubernetes cluster connectivity required for most features—local development without a running k8s/OpenShift target is limited. TLS certificate generation (build-aux/admission_controller_tls/) must succeed or traffic interception fails silently. Windows pkg installer (build-aux/pkg-installer/) requires macOS build environment; cross-compilation may have subtle platform-specific bugs. Protobuf code generation (.protolint.yaml) must run before Go builds or type mismatches occur. Traffic manager image must be accessible to the cluster; private registries require credential configuration. No explicit documentation on minimum Go version (inferred 1.24 from go.mod) or k8s version compatibility.

• Traffic Interception via eBPF or Kernel-level Hooks — Telepresence's core mechanism for redirecting Kubernetes-destined traffic to local machines happens at kernel level; understanding how it hooks system calls is critical for debugging connection issues
• Kubernetes Admission Controllers & Webhooks — build-aux/admission_controller_tls/main.go implements cluster-side webhook handlers; you must understand how admission webhooks intercept and mutate resources to grasp how Telepresence injects itself into cluster operations
• Network Namespace Isolation (Linux netns) — Local traffic routing requires creating or joining Linux network namespaces; the traffic manager likely uses this to segregate cluster-bound traffic from regular host traffic
• TLS Certificate Pinning & mTLS — admission_controller_tls component enforces authenticated communication; securing the tunnel between local client and cluster traffic manager requires understanding certificate validation and rotation
• gRPC Protocol Buffers — .protolint.yaml indicates heavy use of protobuf; inter-component communication (client ↔ traffic manager) likely uses gRPC for efficiency and type safety
• DNS Interception & Spoofing — Allowing local machines to resolve cluster service names (e.g., my-service.default.svc.cluster.local) requires DNS-level spoofing or custom resolvers; critical for seamless cluster access
• Container Image Signing & Supply Chain Security — image-scan.yaml and release.yaml workflows suggest container image verification; Telepresence images deployed to user clusters must be trustworthy, requiring understanding of image signing and attestation

• cloudflare/warp — Alternative zero-trust tunnel solution; similar VPN-like connectivity model but for different use case (secure remote access vs. k8s dev)
• getporter/porter — Cloud-native package management that often works alongside Telepresence for managing cluster deployments
• telepresenceio/telepresence.io — Official documentation and website; contains user guides, API reference, and troubleshooting guides referenced throughout the codebase
• kubernetes/kubernetes — Upstream Kubernetes project; Telepresence integrates deeply with k8s APIs, webhooks (admission controllers), and networking
• envoyproxy/envoy — Potential proxy framework for traffic interception; Telepresence may use similar concepts for network-level packet handling

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 unit tests for cobraparser module with Docker dependency mocking

The cobraparser module (cmd/cobraparser/v2) depends on docker/docker v28.5.2 but has no visible test files in the provided structure. Given Telepresence's complexity with local-to-remote bridging, the CLI parser needs robust testing. A new contributor could add comprehensive unit tests that mock the Docker client to test CLI flag parsing without requiring a real Docker daemon, improving reliability for contributors on different platforms (especially macOS/Windows with Docker Desktop variations).

• [ ] Create cmd/cobraparser/v2/parser_test.go with table-driven tests
• [ ] Mock github.com/docker/docker client using testify/mock or similar
• [ ] Add tests for edge cases: invalid flag combinations, missing required flags, platform-specific paths
• [ ] Update .github/workflows/unit_tests.yaml to include cobraparser test coverage if not already present
• [ ] Document test patterns in CLAUDE.md or add comments for future maintainers

Create GitHub Action workflow for integration tests against test Kubernetes clusters

The repo has dev.yaml, unit_tests.yaml, and release.yaml workflows, but no visible integration test workflow that validates Telepresence against actual Kubernetes clusters (even minimal ones like kind or minikube). Given the core feature is 'Local development against a remote Kubernetes cluster', integration tests are critical. A new contributor could create a reusable GitHub Action workflow that spins up a test cluster and validates key Telepresence operations (intercept, access cluster services, etc.).

• [ ] Create .github/workflows/integration_tests.yaml with kind cluster setup
• [ ] Add steps to test basic intercept functionality using test services from examples/ or build-aux/
• [ ] Create reusable action in .github/actions/kind-cluster-setup/ for cluster initialization
• [ ] Document cluster requirements and test coverage in build-aux/INSTALLERS.md
• [ ] Add job condition to run on PRs targeting main and manual workflow_dispatch trigger

Document architecture and module boundaries in ARCHITECTURE.md for Go packages

The repo has CLAUDE.md (LLM context), GOVERNANCE-maintainer.md, and CODEOWNERS, but no ARCHITECTURE.md explaining the Go module structure. The partial file list shows multiple Dockerfiles, build tools, and the cobraparser module, but new contributors lack guidance on: how cmd/cobraparser relates to other CLI components, the relationship between build-aux tooling and main binaries, and how to navigate the Go package hierarchy. ARCHITECTURE.md would dramatically reduce onboarding friction.

• [ ] Create ARCHITECTURE.md documenting the Go module structure and key packages
• [ ] Explain the purpose of cmd/cobraparser/v2 and how it integrates with main Telepresence CLI
• [ ] Map build-aux/ tools to their corresponding binaries (admission_controller_tls, genversion, pkg-installer, etc.)
• [ ] Add a diagram or table showing Docker image relationships (Dockerfile.client, Dockerfile.traffic, etc.)
• [ ] Include troubleshooting section for common module import/build issues across platforms

• Add unit test coverage for cmd/cobraparser/v2 flag parsing edge cases (missing error handling for invalid cluster URLs, timeout values, namespace selectors) and ensure all CLI flags have corresponding test cases
• Document platform-specific setup in CLAUDE.md for Windows and macOS (build-aux/pkg-installer/ and Dockerfile.winbuild usage); currently no clear guidance on building for non-Linux platforms
• Implement missing integration test for traffic interception in .github/workflows/unit_tests.yaml that verifies local service can reach cluster DNS and services via the traffic manager tunnel

The codebase demonstrates generally good security practices with Dependabot integration and a defined security policy. However, there are concerns with dependency management: an incompatible Docker library version, a deprecated error handling package, and an unreleased Go version. The security policy is well-defined with clear reporting procedures. No hardcoded secrets or injection vulnerabilities were evident from the file structure analysis. Main recommendation: resolve the Docker dependency constraint issue, migrate away from pkg/errors, and use a stable Go version before production deployment.

• High · Docker dependency with incompatible version constraint — go.mod - github.com/docker/docker v28.5.2+incompatible. The go.mod file specifies 'github.com/docker/docker v28.5.2+incompatible', which indicates a major version mismatch. The '+incompatible' suffix suggests the dependency is using pre-v1 semantics but declared as v2+, creating potential compatibility and maintenance issues. This can lead to unexpected breaking changes or security patches not being properly applied. Fix: Update to a compatible version of the Docker library that properly uses semantic versioning. Consider migrating to 'github.com/docker/docker' with a proper v1 or v2 tag if available. Review the Docker library's release notes to ensure compatibility.
• Medium · Indirect dependency on deprecated error handling package — go.mod - github.com/pkg/errors v0.9.1 (indirect). The transitive dependency 'github.com/pkg/errors v0.9.1' is included. This package is no longer maintained and the Go community recommends using the standard library 'errors' package (Go 1.13+) or 'fmt.Errorf()' instead. Using deprecated packages can result in missed security updates and maintenance. Fix: Audit codebase for usage of 'github.com/pkg/errors' and migrate to standard library error handling using 'errors' package or 'fmt.Errorf()'. Remove this dependency from the transitive dependency chain.
• Medium · Multiple Docker-related dependencies without pinned versions — go.mod - indirect Docker/OCI dependencies. Several Docker dependencies (docker-go-connections, docker-go-units, moby/docker-image-spec, opencontainers packages) are indirect dependencies without explicit version management. These can receive updates that may introduce breaking changes or vulnerabilities without explicit control. Fix: Regularly run 'go list -u -m all' to check for available updates. Consider using 'go mod tidy' and reviewing updates to these critical infrastructure dependencies. Implement a dependency update policy with testing.
• Low · Go version 1.24 is pre-release/future version — go.mod - go 1.24. The go.mod specifies 'go 1.24', which is not yet released. Using unreleased Go versions in production can lead to compatibility issues, unavailable security patches, and lack of community support. Fix: Update to the latest stable Go release once this project moves out of development. Document the minimum supported Go version (MSV) for end users. Currently use a stable release like 1.22 or 1.23.

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.