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/zerotier/ZeroTierOne 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.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 7 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ Non-standard license (Other) — review terms

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

What it runs against: a local clone of zerotier/ZeroTierOne — 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 zerotier/ZeroTierOne | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch dev 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 zerotier/ZeroTierOne. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/zerotier/ZeroTierOne.git
#   cd ZeroTierOne
#
# 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 zerotier/ZeroTierOne and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "build.md" \\
  && ok "build.md" \\
  || miss "missing critical file: build.md"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "service/README.md" \\
  && ok "service/README.md" \\
  || miss "missing critical file: service/README.md"

# 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/zerotier/ZeroTierOne"
  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).

ZeroTier is a decentralized virtual networking engine that creates a secure, encrypted peer-to-peer overlay network allowing any device (VMs, containers, apps) to communicate as if they're on the same LAN regardless of physical location. It combines a cryptographically-addressed VL1 peer network with a VL2 Ethernet emulation layer (similar to VXLAN) that includes SDN features like fine-grained access control, network micro-segmentation, and end-to-end encryption. Monolithic but layered architecture: core VL1 peer protocol in node/ (C++), VL2 Ethernet emulation alongside it, platform-specific OS integration in osdep/ (Assembly, Shell, PowerShell), service API in service/ (C++), network controller logic in nonfree/controller/, CLI/UI wrappers in various languages (Java for Android, Objective-C++ for macOS/iOS), and build orchestration via CMakeLists.txt and Makefile with GitHub Actions CI.

Network operators, DevOps engineers, and application developers who need secure remote access to distributed systems without managing VPNs or firewall rules. Also systems integrators building hybrid/multi-cloud deployments where containers and VMs need transparent Layer 2 connectivity across regions and cloud providers.

Production-ready and actively maintained. The repository shows 16+ million lines of C++ code, comprehensive CI/CD pipelines in .github/workflows/, Dockerfiles for release builds, and structured release processes (OFFICIAL-RELEASE-STEPS.md). Recent commits and published release notes indicate active development with enterprise customers. However, the nonfree/ directory indicates some commercial features are source-available rather than fully open.

Low-to-medium risk for production use, but with caveats: the C++ codebase is large (16M+ LOC) and contains platform-specific code across 20+ languages (Assembly, Objective-C++, Java for mobile), increasing maintenance surface area. The split between MPL-licensed open code (node/, service/) and source-available nonfree code (controller/) can create licensing confusion. Dependency on custom protocol implementations rather than standard VPN/networking libraries means security audits are critical.

Active maintenance with GitHub Actions workflows validating Linux builds (validate-linux.sh, validate.yml) and a dedicated central-controller CI pipeline. The repo includes Docker release builds and appears to be in iterative improvement mode based on the structured release process and issue templates for bugs, features, and game-connection issues. No breaking 0.x→1.0 migrations visible, suggesting API stability focus.

Clone and examine the build system: git clone https://github.com/zerotier/ZeroTierOne.git && cd ZeroTierOne && cat build.md (referenced in README as build instructions). Build with: make (Unix/Linux/macOS) or cmake . && cmake --build . (cross-platform). For Docker: docker build -f Dockerfile.release .. No npm/pip in the root—the project uses Make and CMake as primary build systems.

Daily commands: Unix-like systems: make -j$(nproc) then ./zerotier-one (daemon) or ./zerotier-cli (CLI). Windows: cmake -G "Visual Studio 16 2019" . && cmake --build . --config Release. Android/iOS: see platform-specific build in .github/workflows/. Docker: docker build -f Dockerfile.release . && docker run -d --privileged <image>. Full build prerequisites in build.md (compiler toolchains, libsodium, etc. inferred).

• README.md — High-level overview of ZeroTier's architecture as a global Ethernet switch; essential context for understanding the entire project's mission and scope.
• CMakeLists.txt — Master build configuration for a 600-file C/C++ project supporting multiple platforms; contributors must understand how the build system is organized.
• build.md — Platform-specific build requirements and instructions; critical for any developer setting up a development environment.
• .github/workflows/build.yml — Primary CI/CD pipeline; shows automated build, test, and validation steps that all code changes must pass.
• service/README.md — Service API reference documentation; defines the public API surface that applications interact with ZeroTier through.
• SECURITY.md — Security model and cryptographic practices; essential for understanding threat model and encryption guarantees.
• LICENSE-MPL.txt — Mozilla Public License terms; critical for legal compliance and understanding open-source obligations.

• P2P Networking Layer (VL1) (C/C++, libsodium/OpenSSL, UDP, TCP fallback) — Cryptographic peer-to-peer communication, identity verification, session establishment, and NAT traversal via STUN/relay
  • Failure mode: Peer cannot be reached; falls back to relay or queues packets until peer is reachable
• Ethernet — undefined

Add a new platform build target

1. Add platform-specific CMake configuration block in CMakeLists.txt for detecting and configuring target OS (CMakeLists.txt)
2. Create platform-specific source directory (e.g., osdep/YourPlatform/) with system integration code (CMakeLists.txt)
3. Add build job to .github/workflows/build.yml to test compilation on new platform (.github/workflows/build.yml)
4. Document platform-specific requirements, dependencies, and build flags in build.md (build.md)

Add new Service API endpoint

1. Define API message structure and command code in service protocol headers (service/README.md)
2. Implement command handler in the service/command processing layer (service/README.md)
3. Document the new endpoint, parameters, and response format in service/README.md (service/README.md)

Deploy ZeroTier using Docker

1. Review Dockerfile.release to understand runtime dependencies and container entry point (Dockerfile.release)
2. Follow Docker-specific configuration options in README.docker.md (README.docker.md)
3. Use docker-compose or Kubernetes manifests as described in README.docker.md deployment sections (README.docker.md)

Release a new version

1. Follow the step-by-step procedure in OFFICIAL-RELEASE-STEPS.md for version bumping and tagging (OFFICIAL-RELEASE-STEPS.md)
2. Update version strings in CMakeLists.txt and update RELEASE-NOTES.md with changelog (RELEASE-NOTES.md)
3. CI/CD pipeline in .github/workflows/build.yml automatically builds and tests all platforms on tag push (.github/workflows/build.yml)

• C/C++ — High performance, minimal overhead, cross-platform compatibility for daemon running on diverse hardware (IoT, servers, desktops)
• CMake — Build system supporting compilation across Linux, macOS, Windows, BSD, and embedded platforms with minimal duplication
• End-to-end encryption (cryptographically addressed VL1) — Ensures only authorized peers can establish sessions; eliminates need for centralized trust infrastructure beyond controller
• P2P networking — Avoids centralized relay bottlenecks; enables direct peer communication even when both peers are behind NATs (via relay fallback)
• Docker containerization — Simplifies deployment and testing in CI/CD and cloud environments; Dockerfile.release provides reproducible runtime

• Centralized network controller model

  • Why: Simplifies network management, policy enforcement, and member coordination in enterprise environments
  • Consequence: Controller becomes single point of policy; however, data plane (VL1/VL2) operates peer-to-peer even if controller is offline

• Ethernet emulation (VL2) layer over P2P (VL1)

  • Why: Allows existing applications expecting Ethernet/IP to work without modification; enables SDN features like ACLs and flow monitoring
  • Consequence: Added complexity compared to pure IP overlay; higher per-packet overhead due to Ethernet frame wrapping

• Local service API (IPC/TCP) for daemon control

  • Why: Decouples user applications from ZeroTier daemon; simplifies client library implementations across languages
  • Consequence: Local IPC latency adds ~1-5ms per API call; daemon must be running as separate service

• Does not provide DNS/mDNS resolution (reliant on external DNS servers or manual IP management)
• Does not implement VPN-like traffic tunneling from browser or without daemon installation (requires local service)
• Does not handle IoT device provisioning or mobile app silent notifications (domain-specific features handled by clients)
• Not a replacement for firewalls (provides micro-segmentation through ACLs but assumes secure host OS)
• Does not provide high-frequency network latency guarantees suitable for HFT (best-effort overlay, inherits underlying network characteristics)

Privileged mode required: ZeroTier must run as root/administrator to manipulate network interfaces (Tap devices, routing tables)—affects development VMs and Docker setups. Crypto keys matter: the identity/address system is based on Ed25519/Curve25519; key loss = network access loss. Platform fragmentation: Assembly and OS-specific code paths in osdep/ mean code changes can silently break on platforms not in your test matrix (check .github/workflows/validate-linux.sh for CI coverage gaps). Service API coupling: external tools assume the service IPC protocol stability; breaking changes ripple through client tooling. nonfree/controller version lock: the open-source node may not be feature-compatible with latest commercial controller; check version alignment in RELEASE-NOTES.md.

• Virtual Layer 1 (VL1) / Cryptographic Addressing — ZeroTier's peer identity and addressing is based on public-key cryptography (Ed25519), not traditional IP—understanding how addresses derive from keys is fundamental to the security model and why key loss is catastrophic
• Virtual Layer 2 (VL2) / Ethernet Emulation — ZeroTier provides transparent Layer 2 (MAC-based) switching over the peer network, similar to VXLAN; this is why it can emulate LANs—critical for understanding how VMs/containers appear on the same broadcast domain
• Peer-to-Peer with Relay Fallback — ZeroTier attempts direct peer connections but falls back to relaying through central infrastructure if NAT/firewall prevents it; this trade-off between latency and reachability shapes the entire message routing logic
• Network Tap Device (Ethernet Bridge) — ZeroTier integrates with OS-level Tap interfaces (virtual Ethernet adapters) to inject packets into the host network stack—the osdep/ layer's core responsibility, complex across Windows/Linux/macOS
• End-to-End Encryption with Perfect Forward Secrecy — All ZeroTier traffic is encrypted at the packet level using secret keys only you control; understanding the key exchange and session establishment is essential for security audits and threat modeling
• Software-Defined Networking (SDN) Rules — ZeroTier supports fine-grained access control and network micro-segmentation through rules (likely defined in nonfree/controller/); this is the enterprise feature that differentiates it from simple VPNs
• Distributed Hash Table (DHT) or Gossip Protocol — The network likely uses a distributed discovery mechanism (DHT, gossip, or hybrid) to find peers without central coordination; inferred from the 'decentralized' design but not explicitly named in visible files—worth exploring in node/Network.cpp

• wireguard/wireguard — Alternative peer-to-peer VPN using kernel space; solves similar 'secure remote access' problem but Layer 3 only, not Layer 2 Ethernet emulation
• tailscale/tailscale — User-friendly WireGuard-based mesh VPN with centralized coordination; competes on ease-of-use but lacks Layer 2/SDN features that ZeroTier provides
• flannel-io/flannel — Kubernetes network overlay using VXLAN/UDP (similar to ZeroTier's VL2 approach); complements ZeroTier for container networking
• zerotier/ZeroTierUI — Official GUI client for ZeroTier, wraps the service API; useful reference for integrating ZeroTier into user-facing applications
• zerotier/docs — Official documentation repository; source of truth for API specs, architecture diagrams, and deployment guides referenced in build.md

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 CI validation workflow for cross-platform builds

The repo has build.yml and validate.yml workflows, but they lack explicit validation steps for the three major platforms (Linux, macOS, Windows). The file structure shows Dockerfile.ci and Dockerfile.release exist, but the .github/workflows/validate-linux.sh is only for Linux. A new workflow should validate builds on all platforms mentioned in build.md, ensuring CMakeLists.txt and Makefile produce consistent artifacts across Darwin, Linux, and Windows targets.

• [ ] Review existing .github/workflows/build.yml and .github/workflows/validate.yml for coverage gaps
• [ ] Check build.md for all supported platforms and their build requirements
• [ ] Create new .github/workflows/validate-multiplatform.yml with matrix strategy for Linux, macOS, Windows
• [ ] Add validation steps that test CMake and Make builds separately on each platform
• [ ] Verify Dockerfile.ci can be used for containerized validation

Add unit tests for core cryptographic and identity modules

The attic/historic/anode/libanode/ directory contains legacy cryptographic implementations (aes.c, ec.c, identity.c, aes_digest.c). While these are in attic, the main codebase likely has modern equivalents in src/. There are no visible test directories in the file structure for cryptographic operations. Adding a dedicated test suite for identity verification, peer authentication, and encryption would improve code reliability and serve as documentation.

• [ ] Identify cryptographic modules in src/ (search for identity.c, crypto.c, or similar)
• [ ] Create test/crypto/ directory structure
• [ ] Add unit tests for identity generation, verification, and serialization
• [ ] Add unit tests for peer authentication flows
• [ ] Add unit tests for packet encryption/decryption operations
• [ ] Integrate tests into CMakeLists.txt and Makefile build targets

Create platform-specific GitHub Actions for macOS and Windows signing/notarization

The repo contains artwork and binary assets (AppIcon.icns for macOS, AppIcon.ico for Windows), indicating official releases for multiple platforms. However, .github/workflows/ only shows generic build.yml and validate.yml. macOS binaries require code signing and notarization for distribution, and Windows builds benefit from signing. Adding dedicated workflows for these platform-specific requirements would unblock automated official releases and improve the OFFICIAL-RELEASE-STEPS.md process.

• [ ] Review OFFICIAL-RELEASE-STEPS.md to identify signing/notarization requirements
• [ ] Create .github/workflows/macos-release.yml with code signing and notarization steps
• [ ] Create .github/workflows/windows-release.yml with Authenticode signing
• [ ] Add GitHub Secrets configuration documentation for signing certificates
• [ ] Update OFFICIAL-RELEASE-STEPS.md to reference automated workflows
• [ ] Test release artifacts are properly signed in CI before merge

• Add missing unit tests for packet serialization in node/Packet.hpp—there is no test/ directory visible, so adding a basic CTest suite for protocol buffers would improve reliability and help new contributors understand the wire format.
• Document the osdep/ platform abstraction layer with code examples showing how to add support for a new OS (e.g., write a template osdep/NewOSEthernetTap.cpp with comments). Currently it's opaque to newcomers.
• Create a minimal Python or Rust CLI client against the service/ IPC API (documented in service/README.md) as a reference implementation—would help external tool developers and expose API design flaws early.

ZeroTier One demonstrates a reasonable security posture with an established security policy and clear version support strategy. However, there are areas requiring attention: the SECURITY.md documentation is incomplete, legacy code in the attic directory presents maintenance concerns, and dependency security practices are not visible in the provided structure. The project appears to follow good practices with GitHub organization, CI/CD workflows, and Docker support, but would benefit from more transparent security scanning, complete documentation, and cleanup of archived code. The security score reflects a solid foundation with room for improvement in documentation completeness, supply chain security visibility, and legacy code management.

• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file appears to be incomplete. The vulnerability reporting section ends abruptly mid-sentence ('The '), which suggests the security policy documentation is unfinished or improperly maintained. This could lead to confusion for security researchers attempting to report vulnerabilities. Fix: Complete the SECURITY.md file with all required information including: full description of what should be included in vulnerability reports, expected response timeline, and complete PGP key information for encrypted submissions.
• Medium · Historic/Attic Code in Repository — attic/historic/ directory structure. The repository contains an 'attic/historic' directory with old code, including legacy anode implementation. This archived code may contain unpatched security vulnerabilities and could be mistakenly used or referenced. The presence of multiple configuration and implementation files suggests this code is not actively maintained. Fix: Move historic code to a separate archive repository or completely remove from the main codebase. If retention is necessary, clearly document that this code is not supported and should never be used in production. Consider automated scanning of archived code for known vulnerabilities.
• Low · Limited Version Support Window — SECURITY.md - Supported Versions table. Only versions 1.14.x and 1.16.x receive security updates. Versions 1.12.x and older are no longer supported, creating a potential security risk for users running older versions who may not receive critical security patches. Fix: Establish a clear end-of-life (EOL) policy with advance notice periods. Consider providing extended support for critical security issues in older versions, or publish a migration guide to encourage users to upgrade.
• Low · Missing Dependency Manifest — package.json, requirements.txt, go.mod, or equivalent. No dependency/package file content was provided in the analysis. This prevents assessment of third-party dependency security, including known CVEs, outdated libraries, or insecure versions of critical packages. Fix: Implement automated dependency scanning using tools like Dependabot, Snyk, or WhiteSource. Maintain an updated Software Bill of Materials (SBOM). Pin critical dependencies to specific versions and implement regular security audits.
• Low · Limited Visibility into Codebase Security Practices — .github/workflows/ (partial visibility). The provided file structure does not include visible security configuration files (e.g., no .securitypolicies, no security-related GitHub Actions, incomplete CI/CD workflow visibility). This limits assessment of automated security scanning, code review practices, and deployment security. Fix: Implement and document security-focused CI/CD practices including: SAST (Static Application Security Testing), dependency scanning, container scanning for Docker images, and security policy enforcement in pull requests.

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.