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/cloudflare/cloudflared 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
• 14 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• Apache-2.0 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 cloudflare/cloudflared repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cloudflare/cloudflared.

What it runs against: a local clone of cloudflare/cloudflared — 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 cloudflare/cloudflared | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | 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 cloudflare/cloudflared. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cloudflare/cloudflared.git
#   cd cloudflared
#
# 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 cloudflare/cloudflared and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cloudflare/cloudflared(\\.git)?\\b" \\
  && ok "origin remote is cloudflare/cloudflared" \\
  || miss "origin remote is not cloudflare/cloudflared (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/cloudflared/main.go" \\
  && ok "cmd/cloudflared/main.go" \\
  || miss "missing critical file: cmd/cloudflared/main.go"
test -f "cmd/cloudflared/tunnel" \\
  && ok "cmd/cloudflared/tunnel" \\
  || miss "missing critical file: cmd/cloudflared/tunnel"
test -f "carrier/carrier.go" \\
  && ok "carrier/carrier.go" \\
  || miss "missing critical file: carrier/carrier.go"
test -f "cfapi/client.go" \\
  && ok "cfapi/client.go" \\
  || miss "missing critical file: cfapi/client.go"
test -f "client/config.go" \\
  && ok "client/config.go" \\
  || miss "missing critical file: client/config.go"

# 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/cloudflare/cloudflared"
  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).

Cloudflare Tunnel (cloudflared) is a lightweight daemon written in Go that proxies inbound traffic from Cloudflare's edge network to private origins (web servers, APIs, SSH hosts, etc.) without requiring firewall holes or port forwarding. It establishes an outbound-only connection from your origin to Cloudflare's network, then routes requests back through that tunnel, and also enables Layer 4 access to tunnel-protected origins via TCP for SSH/RDP via the cloudflared access command. Monolithic Go application with a CLI-driven architecture: main entry point routes to tunnel subcommands (proxying origins via cloudflared tunnel run) and access subcommands (Layer 4 access to protected origins). Build system uses Makefile (build target: make cloudflared), CI scripts in .ci/scripts/ handle platform-specific packaging, and test infrastructure uses Python (pytest, component-tests.sh) alongside Go tests. Multi-OS support via conditional builds in .ci/scripts/linux/, .ci/scripts/mac/, .ci/scripts/windows/.

Platform engineers, DevOps teams, and system administrators who need to expose internal services (web apps, databases, SSH servers) to the internet securely without managing static IPs or firewall rules. Also used by security-conscious organizations implementing Zero Trust network access patterns.

Highly mature and production-ready. The project is actively maintained by Cloudflare with comprehensive CI/CD across Linux (.ci/linux.gitlab-ci.yml), macOS (.ci/mac.gitlab-ci.yml), and Windows (.ci/windows.gitlab-ci.yml); multi-platform builds (amd64, arm64); and extensive packaging (Debian, RPM, Homebrew, MSI, Docker). Large codebase (1.7M lines of Go) with established release processes (.ci/release.gitlab-ci.yml) and component testing (.ci/scripts/component-tests.sh).

Low risk for production use, but moderate dependency management complexity: Python test dependencies (pytest, pyyaml, websockets, requests) and Go vendored dependencies must be kept in sync. No indication of single-maintainer risk given Cloudflare's organizational backing. Cap'n Proto serialization format (.ci/image/Dockerfile mentions Cap'n Proto at 8.4K lines) is a less common dependency that could create hiring/onboarding friction. Security-critical daemon status means vulnerability response is essential.

Active maintenance evident from multi-platform CI configuration, recent FIPS builds (.ci/scripts/linux/build-packages-fips.sh), vulnerability scanning (.ci/scripts/vuln-check.sh), and formatting checks (.ci/scripts/fmt-check.sh). Security scanning via Semgrep (.github/workflows/semgrep.yml) and GitHub workflows (.github/workflows/check.yaml) indicate ongoing quality gates. CHANGES.md and RELEASE_NOTES files suggest regular release cadence.

git clone https://github.com/cloudflare/cloudflared.git
cd cloudflared
make cloudflared

Install Go (version specified in .ci/scripts/mac/install-go.sh), then run make cloudflared to build the binary. For development, check .golangci.yaml for linting config and .ci/scripts/fmt-check.sh for code style requirements.

Daily commands: Development build: make cloudflared creates binary in ./cloudflared. Run tunnel: ./cloudflared tunnel run --config config.yml (requires Cloudflare account & tunnel token from dashboard). Run access client: ./cloudflared access tcp --hostname origin.example.com --url localhost:PORT for Layer 4 forwarding. Docker: docker run cloudflare/cloudflared:latest tunnel run --token <TOKEN>. See component-tests.sh for full integration test patterns.

• cmd/cloudflared/main.go — Entry point for the cloudflared daemon; every contributor must understand how CLI commands are routed and initialized.
• cmd/cloudflared/tunnel — Core tunnel command implementation; the primary user-facing interface for Tunnel operations and the heaviest responsibility in the codebase.
• carrier/carrier.go — Implements the carrier protocol abstraction for proxying traffic; load-bearing abstraction used by tunnel connections.
• cfapi/client.go — Cloudflare API client that manages tunnel registration, configuration, and metadata; critical dependency for all tunnel operations.
• client/config.go — Configuration parsing and validation; defines how tunnel configs are loaded and validated before runtime.
• cmd/cloudflared/cliutil/handler.go — CLI error and signal handling utilities; orchestrates graceful shutdown and error recovery across all commands.
• cmd/cloudflared/access/cmd.go — Access command implementation for Layer 4 proxying (SSH, RDP); second major feature pillar alongside Tunnel.

Add a New Tunnel Subcommand

1. Define the command handler in cmd/cloudflared/tunnel directory with a Run() function (cmd/cloudflared/tunnel/cmd.go)
2. Register CLI flags specific to the command in cmd/cloudflared/flags/flags.go (cmd/cloudflared/flags/flags.go)
3. Add the subcommand to the tunnel command router in cmd/cloudflared/tunnel/cmd.go (cmd/cloudflared/tunnel/cmd.go)
4. Use cfapi/client.go methods for any Cloudflare API calls needed (cfapi/client.go)
5. Add error handling using cliutil/handler.go patterns for consistent error messages (cmd/cloudflared/cliutil/handler.go)

Add Support for a New Origin Type or Routing Rule

1. Update the tunnel configuration schema in client/config.go to accept new routing parameters (client/config.go)
2. Extend cfapi/tunnel.go to include the new routing metadata in API models (cfapi/tunnel.go)
3. Implement routing logic in the carrier abstraction (carrier/carrier.go or subclasses) (carrier/carrier.go)
4. Add integration tests for the new routing path in cfapi/tunnel_test.go (cfapi/tunnel_test.go)

Add a New Access Layer 4 Protocol Handler

1. Extend cmd/cloudflared/access/cmd.go to add the new protocol as a subcommand option (cmd/cloudflared/access/cmd.go)
2. Implement protocol-specific carrier logic in cmd/cloudflared/access/carrier.go (cmd/cloudflared/access/carrier.go)
3. Add validation rules for the protocol endpoint in cmd/cloudflared/access/validation.go (cmd/cloudflared/access/validation.go)
4. Use cfio/copy.go for efficient bidirectional I/O with the remote origin (cfio/copy.go)

Add Platform-Specific Service Management

1. Implement platform-specific service lifecycle in cmd/cloudflared/[linux|macos]_service.go (cmd/cloudflared/linux_service.go)
2. Use the common_service.go abstraction to share code with other platforms (cmd/cloudflared/common_service.go)
3. Register the service command in the main CLI router (cmd/cloudflared/main.go) (cmd/cloudflared/main.go)
4. Add CI/CD scripts in .ci/scripts/[platform]/ to test service installation and startup (.ci/scripts/linux/build-packages.sh)

• Go — Single compiled binary with minimal dependencies; efficient for a lightweight daemon running on customer infrastructure with low resource overhead.
• WebSocket (carrier/websocket.go) — HTTP-friendly protocol for NAT/firewall traversal; Cloudflare edge can push traffic via standard HTTPS ports without requiring inbound firewall rules on customer origins.
• systemd/launchd/Windows Services — Platform-native service management ensures cloudflared integrates cleanly with OS lifecycle and runs in background without user intervention.
• REST API (cfapi/) — Standard interface for tunnel CRUD, routing updates, and origin metadata; decoupled tunnel lifecycle from daemon implementation.
• YAML config files (client/config.go) — Human-readable declarative config; avoids CLI flag complexity and enables version control of tunnel routing policies.

• Tunnel proxying via WebSocket instead of raw TCP relay
  • Why: WebSocket works through HTTP proxies and NAT; compatible with HTTP-only networks and Cloudflare's edge infrastructure.
  • Consequence: Slight latency overhead vs. direct TCP (1–10ms per hop); cannot proxy arbitrary non-HTTP-compatible Layer 7 protocols.

Cloudflare account requirement: Tunnel creation and token generation require Cloudflare dashboard access; local testing without a valid token will fail. Cap'n Proto: Serialization schema changes require regenerating Go code from .capnp schema files; missing build steps cause silent failures. Platform-specific binary signing: Windows MSI (.ci/scripts/windows/sign-msi.ps1) requires certificate; macOS builds need Apple signing certs (see .ci/scripts/mac/build.sh). FIPS builds: Separate FIPS-compliant build path (.ci/scripts/linux/build-packages-fips.sh) must be used for FedRAMP/FIPS 140-2 compliance; regular builds are NOT FIPS-compliant. Tunnel token security: Test tokens leaked in git history or CI logs compromise tunnel security; rotate immediately. Config file path: cloudflared tunnel run --config expects YAML; missing or malformed config defaults to standard locations (~/.cloudflared/config.yml).

• Reverse Proxy / Outbound Tunnel Connection — cloudflared establishes an outbound-only persistent connection to Cloudflare edge (no inbound firewall holes required); understanding this model is crucial for deployment security architecture
• Cap'n Proto (Serialization Format) — The 8.4K lines of Cap'n Proto in the codebase handle efficient, schema-evolved message passing between tunnel components; you'll need to understand this to modify internal protocol structures
• WebSocket Bidirectional Signaling — HTTP requests are multiplexed over WebSocket connections between cloudflared and Cloudflare edge; understanding this flow is essential for debugging request routing failures
• TCP/UDP Tunneling (Layer 4 Forwarding) — The cloudflared access command implements Layer 4 proxying for non-HTTP protocols (SSH, RDP, databases); the architecture differs significantly from HTTP/WebSocket tunnel mode
• Zero Trust / Connector Pattern — cloudflared implements Cloudflare's Zero Trust architecture where all traffic flows through identity-verified connectors; this design philosophy permeates authentication, authorization, and audit logging
• FIPS 140-2 Compliance Builds — Separate build path (.ci/scripts/linux/build-packages-fips.sh) produces FedRAMP/compliance-certified binaries; requires understanding cryptographic library constraints and platform-specific build flags
• Multi-Platform Binary Packaging (Debian/RPM/MSI/Homebrew) — The .ci/scripts/ directory contains non-trivial platform-specific packaging logic; understanding each platform's requirements (signing, certificate chains, installation paths) is necessary for releases

• cloudflare/warp-cli — Official Cloudflare WARP client providing similar Layer 4 tunnel access for end-users without requiring cloudflared access CLI on the client side
• cloudflare/ssl-for-origin — Companion tool for establishing mTLS between cloudflared and origin servers, solving encryption between tunnel and backend
• kubernetes/ingress-cloudflare-tunnel — Kubernetes Ingress controller using cloudflared as the tunneling backend for exposing cluster services
• cloudflare/argo-tunnel — Historical predecessor (now superseded by Cloudflare Tunnel); documents legacy architecture and migration path
• cloudflare/cloudflare-docs — Official documentation repository where Cloudflare Tunnel user guides and API references live

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 comprehensive unit tests for cfapi package modules

The cfapi package contains critical API client code (hostname.go, ip_route.go, tunnel.go, virtual_network.go) with filter variants, but only some files have corresponding _test.go files. hostname_test.go, ip_route_test.go, tunnel_test.go, and virtual_network_test.go exist, but base_client.go lacks tests. Additionally, the filter modules (tunnel_filter.go, ip_route_filter.go, virtual_network_filter.go) have no test coverage. This is a foundational client library that needs robust testing before new features are added.

• [ ] Create cfapi/base_client_test.go with tests for HTTP methods, error handling, and retry logic
• [ ] Create cfapi/tunnel_filter_test.go testing filter creation and query parameter building
• [ ] Create cfapi/ip_route_filter_test.go with filter composition tests
• [ ] Create cfapi/virtual_network_filter_test.go with filter tests
• [ ] Ensure >80% code coverage for all cfapi modules using 'go test -cover ./cfapi'
• [ ] Run golangci-lint (.golangci.yaml) to verify no issues introduced

Add WebSocket carrier unit tests for edge cases and error scenarios

The carrier package implements WebSocket communication (carrier/websocket.go) which is critical for tunnel operation. While carrier_test.go and websocket_test.go exist, the test coverage appears incomplete based on typical WebSocket edge cases. This module handles connection state, message framing, and error propagation—all critical for tunnel reliability. Expanding tests for connection failures, malformed frames, and reconnection logic would significantly improve stability.

• [ ] Review carrier/websocket.go for error paths not covered in websocket_test.go
• [ ] Add tests for connection timeout scenarios and graceful shutdown
• [ ] Add tests for handling malformed WebSocket frames and protocol violations
• [ ] Add tests for reconnection logic and backoff behavior
• [ ] Add tests for concurrent message handling and race conditions using -race flag
• [ ] Verify test coverage reaches >85% for websocket.go using 'go test -cover ./carrier'

Create GitHub Actions workflow for Go vulnerability scanning on pull requests

The repo has .ci/scripts/vuln-check.sh and .vulnignore file, indicating vulnerability checking is important, but there's no dedicated GitHub Actions workflow for it (.github/workflows only has check.yaml and semgrep.yml). The existing .gitlab-ci.yml handles this via GitLab CI, but new contributors using GitHub forks won't see vuln scan results until merge. Adding a GitHub Action would improve security feedback for contributors and catch supply-chain issues early.

• [ ] Create .github/workflows/vuln-check.yaml that runs 'govulncheck ./...' on pull requests
• [ ] Ensure workflow respects .vulnignore file for known/acceptable vulnerabilities
• [ ] Configure workflow to fail on new vulnerabilities but warn on ignored ones
• [ ] Test locally with: go install golang.org/x/vuln/cmd/govulncheck@latest && govulncheck ./...
• [ ] Add step to also check Python dependencies (requirements.txt) using 'safety check' or 'pip-audit'
• [ ] Document in CONTRIBUTING.md (if exists) or README.md how to run locally

• Add missing integration tests for Layer 4 TCP tunneling (access subcommand) in .ci/scripts/component-tests.sh; currently component tests focus on HTTP tunnel paths, leaving SSH/RDP access paths under-tested.
• Document the Cap'n Proto schema build process and schema file locations in a DEVELOPMENT.md file; new contributors struggle to regenerate code after schema changes without clear instructions.
• Add platform-specific quick-start guides in docs/ or README.md for Windows PowerShell users (.ci/scripts/windows/builds.ps1 and installer configuration are not documented for developers trying to build locally on Windows).

• High · Outdated Python Dependencies with Known Vulnerabilities — Dependencies/Package file content (requirements or similar). The dependencies file contains several outdated packages with known security vulnerabilities: requests==2.28.2 (CVE-2023-32681 - potential cookie handling issues), pyyaml==6.0.1 (multiple CVEs), and websockets==11.0.1. These versions are significantly behind current releases and likely contain patched vulnerabilities. Fix: Update all dependencies to their latest stable versions: requests>=2.31.0, pyyaml>=6.0.1 with security patches, websockets>=12.0, pytest>=7.4.0. Implement automated dependency scanning and regular update cycles.
• Medium · Insecure Deserialization Risk in PyYAML — cfsetup.yaml and any Python scripts parsing YAML configuration. PyYAML 6.0.1 may be vulnerable to arbitrary code execution through unsafe deserialization if using yaml.load() without a Loader parameter. The codebase uses pyyaml which could be exploited if processing untrusted YAML input. Fix: Ensure all yaml.load() calls explicitly specify Loader=yaml.SafeLoader or yaml.FullLoader with validation. Use yaml.safe_load() for untrusted input. Audit all YAML parsing code paths.
• Medium · Requests Library HTTP Request Vulnerabilities — cfapi/base_client.go and any Python HTTP client code. requests==2.28.2 is outdated and may have issues with cookie handling, redirect validation, and HTTP request processing. The library version is from early 2023 and has since received security patches. Fix: Upgrade requests to version 2.31.0 or later. Review any code that handles cookies, redirects, or processes responses from untrusted sources.
• Medium · Go Version Pinning to 1.26.2 — Dockerfile (ARG golang:1.26.2). The Dockerfile pins Go version to 1.26.2, which may contain unpatched security vulnerabilities. While Go has excellent security practices, pinning to a specific version means security patches won't be automatically applied. Fix: Update to the latest stable Go version (1.22.x or later as of 2024). Implement a process to regularly update the base image and Go version. Consider using a version range or latest stable tag with security scanning.
• Medium · Distroless Base Image Without Vulnerability Scanning — Dockerfile (FROM gcr.io/distroless/base-debian13:nonroot). The Dockerfile uses gcr.io/distroless/base-debian13:nonroot which is good practice, but there's no evidence of image scanning or verification (no image digest pinning, no security scanning in CI/CD visible). Fix: Pin the distroless image to a specific digest rather than tag: gcr.io/distroless/base-debian13:nonroot@sha256:... Implement automated image scanning in CI/CD pipeline (using tools like Trivy or Grype). Add image signing and verification.
• Low · Missing Security Headers Documentation — carrier/websocket.go, cfapi/base_client.go. As a tunnel client that proxies traffic, there's no visible documentation or implementation details about security headers passed through the tunnel or configurable security policies. Fix: Document security header handling policies. Ensure sensitive headers (Authorization, Cookies) are properly validated and forwarded securely. Consider implementing header filtering/sanitization.
• Low · CI/CD Pipeline Visibility and Security — .gitlab-ci.yml, .github/workflows/. Multiple CI/CD configuration files (.gitlab-ci.yml, GitHub Actions) are present but not visible for review. Potential risks include unsigned builds, unverified dependencies, or insecure artifact handling. Fix: Implement signed commits and tags. Use SLSA framework for build provenance. Scan all build artifacts for vulnerabilities. Implement pull request security reviews before merging.
• Low · Potential Hardcoded Configuration Risk — undefined. The presence of config files (client/config.go) and setup files (cfsetup.yaml) suggests configuration management. Without reviewing the actual content, there's a risk of hardcoded secrets or unsafe defaults Fix: undefined

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.