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/SagerNet/sing-box 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 — Single-maintainer risk — review before adopting

• Last commit 4d ago
• 2 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% 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 SagerNet/sing-box repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SagerNet/sing-box.

What it runs against: a local clone of SagerNet/sing-box — 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 SagerNet/sing-box | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch testing exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "box.go" \\
  && ok "box.go" \\
  || miss "missing critical file: box.go"
test -f "adapter/inbound/adapter.go" \\
  && ok "adapter/inbound/adapter.go" \\
  || miss "missing critical file: adapter/inbound/adapter.go"
test -f "adapter/outbound/adapter.go" \\
  && ok "adapter/outbound/adapter.go" \\
  || miss "missing critical file: adapter/outbound/adapter.go"
test -f "adapter/router.go" \\
  && ok "adapter/router.go" \\
  || miss "missing critical file: adapter/router.go"
test -f "adapter/dns.go" \\
  && ok "adapter/dns.go" \\
  || miss "missing critical file: adapter/dns.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 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
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/SagerNet/sing-box"
  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).

sing-box is a universal proxy platform written in Go that acts as a configurable proxy server supporting multiple protocols (HTTP, SOCKS, DNS, etc.). It provides a unified framework for handling inbound/outbound connections with pluggable protocol adapters, making it suitable for VPN clients, corporate proxies, and routing infrastructure that need protocol flexibility without reimplementing core networking logic. Modular monolith: adapter/ package contains abstract interfaces (adapter/inbound/adapter.go, adapter/outbound/adapter.go, adapter/dns.go) with registry-based plugin discovery (adapter/inbound/registry.go, adapter/endpoint/registry.go, adapter/certificate/registry.go). Protocol implementations live in parallel packages (implied: protocol-specific adapters). Manager objects in each subsystem (adapter/inbound/manager.go, adapter/endpoint/manager.go) orchestrate lifecycle.

DevOps engineers, proxy/VPN platform builders, and systems integrators who need to deploy multi-protocol proxy infrastructure across Linux, macOS, Windows, OpenWrt, and Alpine systems. Contributors are typically Go developers familiar with networking stacks and proxy protocols.

Production-ready and actively maintained. The codebase spans 3.3M+ lines of Go, has comprehensive CI/CD via GitHub Actions (build.yml, test.yml, docker.yml, linux.yml), systematic package management (.fpm_* files for multiple distros), and cross-platform support (Dockerfile, macOS/Windows-specific setup scripts). Last activity visible in the file structure shows ongoing work on dependencies and clients.

Moderate risk from complexity: the adapter pattern with multiple inbound/outbound/certificate/endpoint/DNS managers creates coupling across many files. Single maintainer (nekohasekai) holds copyright and final decision authority. Cronet integration (.github/CRONET_GO_VERSION, update_cronet*.sh) adds external dependency risk. No visible vulnerability disclosure process in ISSUE_TEMPLATE. GPL v3 license with non-derivative clause may restrict commercial forks.

Active dependency management via renovate.json and update_*.sh scripts. Ongoing Cronet (Chromium networking) integration and cross-platform binary builds. Client updates tracked in update_clients.sh. Multiple GitHub Actions workflows suggest CI focus on Linux ARM/x86, Docker image distribution, and linting (golangci.yml config present).

Clone and build with Go: git clone https://github.com/SagerNet/sing-box.git && cd sing-box && make (Makefile present in root). For Alpine/OpenWrt: .github/build_alpine_apk.sh and .github/build_openwrt_apk.sh are available. For Docker: docker build -f Dockerfile . or .github/build_alpine_apk.sh for lighter apk variant.

Daily commands: Start with Makefile targets: make help (assumed) to see available targets. Build binary: make build or make release (inferred). For development iteration, use go run . -c config.json (config filename inferred from proxy patterns). Docker: docker run sing-box after building Dockerfile. Requires configuration file (JSON format, not in file list but standard for proxy platforms).

• box.go — Core entry point for the sing-box proxy engine; initializes all subsystems and manages the application lifecycle.
• adapter/inbound/adapter.go — Defines the Inbound interface that all proxy protocols (HTTP, SOCKS, Shadowsocks, etc.) must implement.
• adapter/outbound/adapter.go — Defines the Outbound interface for routing and forwarding traffic to upstream servers or proxies.
• adapter/router.go — Core routing logic that matches connections against rules and dispatches them to appropriate outbounds.
• adapter/dns.go — DNS resolution abstraction layer handling fake-IP, caching, and custom DNS server integration.
• cmd/sing-box/cmd.go — CLI command dispatcher and main entry point for the executable; handles run, check, and generate subcommands.
• adapter/service/registry.go — Registry pattern for dynamically loading and managing extensible services within the proxy platform.

Add a New Inbound Protocol

1. Implement the Inbound interface from adapter/inbound/adapter.go (Listen, Close, ListenerAddr, etc.) (adapter/inbound/adapter.go)
2. Register your inbound type in the registry by creating a constructor function (adapter/inbound/registry.go)
3. Add marshaling logic to parse config JSON/YAML into your inbound struct (adapter/inbound/adapter.go)
4. Implement NewConnection() to parse protocol headers and call router.RouteConnection() (box.go)

Add a New Outbound Protocol

1. Implement the Outbound interface from adapter/outbound/adapter.go (DialContext, ListenPacket, etc.) (adapter/outbound/adapter.go)
2. Register your outbound type constructor in the registry (adapter/outbound/registry.go)
3. Implement dial logic to connect to the upstream server with protocol-specific handshake (adapter/outbound/adapter.go)
4. Add to outbound manager so router can select it during rule matching (adapter/outbound/manager.go)

Add a New Routing Rule Type

1. Define a rule struct with a Match(metadata) bool method in a new rule package (adapter/rule.go)
2. Register your rule type in the rule registry with a constructor (adapter/rule.go)
3. Add marshaling logic to parse rule config from YAML/JSON (adapter/rule.go)
4. Router calls rule.Match() on incoming connections; returning true triggers rule's target outbound (adapter/router.go)

Add a Custom Service

1. Implement the Service interface from adapter/service/adapter.go (Start, Close) (adapter/service/adapter.go)
2. Register your service constructor in the service registry (adapter/service/registry.go)
3. Add configuration struct and marshaling to parse service config (adapter/service/adapter.go)
4. Services are instantiated during box initialization; integrate with box.go lifecycle (box.go)

• Go — Cross-platform compilation, efficient concurrency with goroutines, fast startup, minimal runtime overhead ideal for proxy use
• TUN device integration — System-wide traffic capture on Linux/macOS/Windows/Android for transparent proxy without per-app configuration
• gRPC (inferred from protogen) — Efficient remote control API and inter-process communication for management interfaces
• Registry pattern — Extensible plugin architecture allowing third-party inbound/outbound protocols and services without core modification
• Fake-IP DNS — Reduces DNS leaks and enables transparent routing without knowing upstream destinations in advance

• Centralizer router-first architecture vs. per-inbound routing

  • Why: Allows complex rule matching and outbound selection across all protocols uniformly
  • Consequence: All inbound types must normalize to common metadata format; tighter coupling to router interface

• Synchronous rule matching (sequential) vs. indexed/trie-based fast-path

  • Why: Simpler implementation and extensibility; supports arbitrary rule types (Geosite, ASN, regex, etc.)
  • Consequence: Latency increases with rule count; may require optimization for large rule sets via caching

• Fake-IP pool management vs. DNS-only hijacking

  • Why: Enables transparent routing and GEOIP rule matching without real DNS queries
  • Consequence: Requires additional metadata storage; potential IP conflicts if pool exhausted

• OS-specific platform adapters vs. pure userspace implementation

  • Why: Native TUN, certificate installation, and system integration on supported platforms
  • Consequence: Increased maintenance burden across iOS, Android, macOS, Windows, Linux; feature parity gaps possible

• Does not handle VPN protocol implementation directly (acts as a proxy platform, not a VPN client)
• Does not provide built-in web UI or dashboard (can be added as external service)
• Not designed for real-time video streaming optimization (standard proxy behavior)
• Does not implement QUIC protocol natively (delegates to outbound handlers)
• Windows 7 and older macOS versions require special Go setup; not primary targets

Cronet dependency requires version pinning via .github/CRONET_GO_VERSION; mismatched versions cause linking failures. Cross-compilation requires platform-specific Go versions (old macOS 10.13 and Windows 7 need custom setup per .github/ scripts; modern Go may not support these). Certificate manager has darwin-specific code path (adapter/certificate_darwin.go); other OS implementations absent or implicit, risking missed platform requirements. GPL v3 + non-derivative clause creates licensing friction for proprietary extensions. Configuration format not defined in repo; users must consult external documentation.

• Adapter Pattern / Protocol Plugin Architecture — sing-box's entire extensibility hinges on adapter interfaces (Inbound, Outbound, DNS, Certificate, Endpoint); understanding how to add support for a new protocol requires fluency in this pattern
• Multiplexed Protocol Handling (Mux) — Proxy platforms must route multiple concurrent streams over single connections; sing-box likely implements H2Mux or similar; critical for performance and connection pooling
• TLS/Certificate Chain Validation — adapter/certificate/manager.go handles trust anchors and renewal; HTTPS interception and client authentication depend on this; darwin-specific code hints at OS-level cert store integration
• DNS Over HTTPS (DoH) / DNS Over TLS (DoT) — adapter/dns.go provides DNS resolution; modern proxies encrypt DNS queries; sing-box likely supports encrypted DNS as alternative to plaintext
• Cross-Compilation and Platform Abstraction — sing-box targets Linux, macOS, Windows, OpenWrt, Alpine via single codebase; platform-specific files (certificate_darwin.go) and build scripts (.github/setup_go_for_*.sh) reveal build complexity and ABI concerns
• FakeIP / Local DNS Spoofing — adapter/fakeip.go suggests local DNS hijacking for transparent proxying; assigns fake IPs to block DNS queries, routing via proxy instead; key for client-transparent operation
• Registry Pattern / Service Locator — adapter/inbound/registry.go, adapter/outbound/registry.go, adapter/certificate/registry.go all implement discovery; allows runtime loading of protocol handlers without hard-coded imports

• shadowsocks/shadowsocks-core — Alternative proxy protocol implementation; sing-box likely wraps or competes with this for encryption-based proxying
• v2ray/v2ray-core — Predecessor universal proxy platform with similar adapter architecture; sing-box is spiritual successor with cleaner Go design
• clash/clash — Popular rule-based proxy router; sing-box shares goal of unified multi-protocol handling with different routing philosophy
• SagerNet/sing — Companion library repository (parent org); likely contains shared utilities and base types used by sing-box
• SagerNet/gvisor — SagerNet-maintained fork of gVisor; used by sing-box for userspace network stack and traffic interception

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 adapter/certificate management

The certificate adapter system (adapter/certificate/*.go, adapter/certificate_darwin.go, adapter/certificate_provider.go) lacks visible test coverage. Given that certificate management is critical for proxy functionality, adding tests for certificate lifecycle, provider registration, and platform-specific behaviors (especially Darwin) would improve reliability and catch regressions early.

• [ ] Create adapter/certificate_test.go with tests for certificate manager initialization and lifecycle
• [ ] Add adapter/certificate/registry_test.go to test provider registration and lookup logic
• [ ] Create adapter/certificate_darwin_test.go for macOS-specific certificate handling (mock darwin syscalls)
• [ ] Test certificate provider interface implementation with mock providers
• [ ] Ensure tests cover error cases (invalid certs, provider failures)

Implement missing GitHub Actions workflow for platform-specific builds

The repo has workflows for linux.yml, docker.yml, and build.yml, but lacks dedicated workflows for macOS (darwin) and Windows builds despite having platform-specific code in adapter/certificate_darwin.go and helper scripts (.github/setup_go_for_macos1013.sh, .github/setup_go_for_windows7.sh). Adding these workflows would ensure cross-platform compatibility and catch platform-specific regressions.

• [ ] Create .github/workflows/macos.yml to build and test on macOS runners with proper Go version setup using .github/setup_go_for_macos1013.sh
• [ ] Create .github/workflows/windows.yml for Windows builds/tests, leveraging .github/setup_go_for_windows7.sh for legacy Windows 7 compatibility testing
• [ ] Both workflows should mirror the test and build steps from linux.yml with platform-appropriate settings
• [ ] Add caching for Go modules to speed up builds

Add integration tests for endpoint and service adapter managers

The adapter system has manager and registry patterns (adapter/endpoint/manager.go, adapter/service/manager.go, adapter/inbound/manager.go) but adapter/inbound_test.go suggests minimal test coverage for these critical manager implementations. Adding comprehensive integration tests would validate the manager lifecycle, concurrent operations, and inter-adapter communication.

• [ ] Create adapter/endpoint/manager_test.go testing endpoint registration, lifecycle, and concurrent access patterns
• [ ] Create adapter/service/manager_test.go for service manager initialization, service registration/deregistration
• [ ] Extend adapter/inbound_test.go with tests for manager operations and multi-inbound coordination
• [ ] Add tests for error handling when registries fail or managers conflict
• [ ] Test cleanup and shutdown sequences to prevent resource leaks

• Add unit tests for adapter/dns.go and adapter/connections.go; currently no *_test.go files visible in the adapter/ tree despite complex state management, making DNS routing and connection tracking behavior opaque.
• Document the Adapter interface contract: create CONTRIBUTING.md with worked example of implementing a new protocol adapter (e.g., a minimal UDP-only handler) in adapter/yourprotocol/; this is the most common extension point but lacks inline guidance.
• Add missing OS implementations: create adapter/certificate_windows.go and adapter/certificate_linux.go mirroring adapter/certificate_darwin.go; currently only macOS has platform-specific cert handling, leaving other systems with incomplete behavior.

The sing-box codebase demonstrates reasonable security practices with active use of CI/CD pipelines and no obvious hardcoded credentials. However, several improvements are recommended: (1) Use explicit, stable versions for base images instead of 'latest' tags, (2) Add security hardening to Docker images (non-root users, read-only filesystems), (3) Integrate automated security scanning (SAST, dependency scanning, container scanning) into CI/CD workflows, (4) Exclude git history from Docker build context, and (5) Implement supply chain security measures (SBOM, signed releases). The project appears well-maintained with proper GPL licensing, but explicit security hardening and automated vulnerability detection would improve the overall security posture.

• Medium · Go Version in Docker Base Image — Dockerfile (line 1). The Dockerfile uses golang:1.25-alpine as the base image. Go 1.25 is a future/unreleased version at the time of analysis. Using development or unreleased versions may introduce instability and security issues. Verify this is intentional and monitor for security updates. Fix: Use a stable, released Go version (e.g., golang:1.23-alpine or later stable release). Ensure regular updates to patch security vulnerabilities.
• Medium · Insufficient Alpine Base Image Security Hardening — Dockerfile (line 18-21). The final stage Dockerfile uses 'alpine AS dist' without specifying a version tag. Using 'latest' implicitly can lead to unpredictable updates. Additionally, the second stage installs packages but doesn't implement additional security hardening like read-only root filesystem or non-root user execution. Fix: Specify explicit Alpine version tag (e.g., alpine:3.19). Add a non-root user for running sing-box, set appropriate file permissions, and consider using read-only filesystem where possible.
• Low · Git History Exposed in Build Context — Dockerfile (line 12). The Dockerfile runs 'git rev-parse --short HEAD' during build, which means the entire git history is copied into the build context. This could expose sensitive information from git history if the image is compromised. Fix: Use .dockerignore to exclude .git directory from build context. Alternatively, pass commit/version as build arguments instead of computing them from git history.
• Low · Missing Security Scanning in CI/CD — .github/workflows/build.yml, .github/workflows/lint.yml. While GitHub Actions workflows exist (.github/workflows), there is no visible evidence of container image scanning, dependency vulnerability scanning (e.g., nancy, trivy), or SAST tools configured in the workflow files listed. Fix: Integrate security scanning tools: container image scanning (trivy), Go dependency scanning (nancy/govulncheck), and SAST (golangci-lint with security rules). Add these to CI/CD pipelines.
• Low · Incomplete License Header in README — README.md (License section). The LICENSE section in README.md is incomplete and truncated ('In addition, no derivative work may use the name or imply association with this applic'). While not a direct security vulnerability, incomplete legal documentation can create compliance issues. Fix: Complete the license header in README.md and ensure the full LICENSE file matches the documented license text.
• Low · No Explicit Secret Management Configuration Visible — cmd/, adapter/, box.go. While no hardcoded secrets were found in the analyzed file structure, there is no visible evidence of secret management practices, environment variable validation, or configuration security patterns in the provided codebase structure. Fix: Implement secure configuration management: validate all environment variables, use secure secret storage (not in code), implement secrets rotation policies, and document security-sensitive configuration options.
• Low · Missing SBOM and Supply Chain Security — Repository root, .github/workflows/. No visible Software Bill of Materials (SBOM) generation or supply chain security measures (e.g., signed releases, provenance) in the provided file structure. Fix: Generate SBOM using tools like syft, sign releases with cosign, and publish provenance information using SLSA framework to enhance supply chain security.

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.