How ref1nd/sing-box works
1. Overall shape
- This is a Go-based proxy platform, not a single app type. The repo builds a core engine plus multiple front-ends: a CLI daemon, mobile/library bindings (experimental/libbox), and platform-specific services/helpers.
- The core idea is: configuration in → adapters/rules/transport assembly → runtime packet/connection processing → outbound/service/DNS handling → platform integration.
2. Core orchestration layer
- box.go, daemon/, and cmd/sing-box/ are the main orchestration entry points.
- The CLI subcommands cover running the box, config validation/formatting, generating artifacts, GeoIP/Geosite/rule-set tooling, and diagnostics.
- daemon/started_service.proto and generated gRPC files indicate a small daemon-control boundary for services to start/attach to a running instance.
3. Configuration and option model
- option/ defines the external configuration schema and strongly typed config objects for all subsystems: inbounds, outbounds, DNS, routes, endpoints, services, TLS, WireGuard, etc.
- constant/ contains shared enums, paths, protocol names, OS tags, timeouts, and other cross-cutting values.
- include/ exposes build-time feature gates and stubs so the same codebase can compile with different capabilities per platform.
4. Adapter layer as the composition boundary
- adapter/ is the central “wiring” layer. It turns config objects into runtime managers/registries for inbounds, outbounds, DNS, endpoints, services, certificates, and routing-related helpers.
- The presence of manager.go and registry.go patterns across subpackages shows a plugin-like architecture: adapters are registered, instantiated, and lifecycle-managed rather than hard-coded.
- This layer is where different subsystems are connected together before traffic starts flowing.
5. Protocol implementations
- protocol/ contains protocol-specific inbound/outbound handlers: SOCKS, HTTP, Shadowsocks, VMess, VLESS, Trojan, Hysteria/Hysteria2, TUIC, Naive, AnyTLS, ShadowTLS, WireGuard, Tor, Direct, Block, DNS, Tailscale, etc.
- Each protocol package is the concrete implementation behind an adapter and usually comes in paired inbound/outbound forms where applicable.
- This is the main traffic-processing layer: it accepts connections from listeners or tunnels and transforms them into proxied or direct egress connections.
6. Routing and policy engine
- route/ is the decision layer for where traffic goes.
- route/router.go, route/rule/, and route/conn.go indicate the router evaluates metadata such as domain, IP/CIDR, process name/path, port, inbound/outbound identity, network type, Wi-Fi info, users, and rule sets.
- Rule sets can be local or remote, and there are semantic/update validation tests, suggesting routing is a first-class dynamic policy system rather than a static ACL list.
7. DNS subsystem
- dns/ is a full DNS stack with clients, router, and multiple transports.
- dns/transport/ supports upstream DNS over UDP, TCP, TLS, HTTPS, QUIC/HTTP3, local/system resolution, hosts-file resolution, fake IP mapping, mDNS, DHCP, and platform-local resolvers.
- The DNS layer is tightly integrated with routing and fake-IP behavior, so DNS answers can drive later connection routing decisions.
8. Connection ingress and network interception
- common/listener/, common/pipelistener/, common/redir/, common/mux/, common/proxybridge/, and protocol/tun/ cover how traffic enters the engine.
- The repo supports multiple ingress styles: plain listeners, transparent redirection/TProxy, TUN-based interception, and multiplexed streams.
- common/process/, route/process_cache.go, and platform-specific code show the engine can enrich flows with process/device metadata for policy decisions.
9. Shared transport and TLS infrastructure
- common/tls/, common/httpclient/, common/dialer/, common/sniff/, common/ja3/, common/ktls/, common/tlsfragment/, and common/tlsspoof/ are the reusable networking primitives.
- These packages provide dialers, HTTP clients, TLS client/server variants, ECH/REALITY support, fragmentation/spoofing, sniffers for protocol detection, and platform-specific crypto/network optimizations.
- This is the foundational utility layer used by both protocol implementations and services.
10. Services and platform integration
- service/ contains OS/service-side integrations such as ACME, certificate management, OCM/CCM, DERP, OOM killer handling, resolved integration, origin CA handling, and SSM API.
- common/settings/, common/schannel/, common/windivert/, common/settings/proxy_*, and common/redir/* reflect platform-specific behavior on Android, Apple, Linux, Windows, and OpenWrt-like environments.
- These parts are the boundary to the host OS: system proxy settings, Wi-Fi/network state, drivers, redirection, and resolver integration.
11. Experimental APIs and embedded libraries
- experimental/clashapi/ and experimental/v2rayapi/ expose compatibility APIs and stats/control surfaces for external clients.
- experimental/libbox/ is the library/FFI-facing layer, with command APIs, profile management, telemetry, and platform hooks for mobile and desktop app embedding.
- include/*_stub.go and platform-specific source files show these APIs are selectively compiled depending on target platform and enabled features.
12. Transport extensions and ecosystem compatibility
- transport/ adds protocol-adjacent transports and encapsulations: V2Ray HTTP/WS/gRPC/QUIC variants, Trojan transport helpers, simple-obfs, SIP003 plugin compatibility, and WireGuard device/endpoint support.
- This layer is where the project interoperates with external ecosystems and legacy clients/servers while keeping the core protocol layer cleaner.
13. Data flow to draw in a diagram
- Typical inbound flow: OS/network listener or TUN/TProxy receives traffic → sniffing/metadata extraction → route/rule evaluation → DNS lookup if needed → selected outbound/protocol handler → transport/TLS/dialer stack → remote endpoint.
- Typical control/config flow: config/options parsed → adapter registries instantiate subsystems → services and listeners start → runtime telemetry/control APIs observe and adjust behavior.
- DNS and routing are not peripheral; they are central decision points that influence connection establishment.
14. Build, packaging, and validation boundaries
- cmd/internal/ hosts build tooling, code generation, version updates, and platform packaging helpers.
- release/, Dockerfile*, .github/workflows/, and the docs/ tree show this repo ships across many targets and package formats, with CI-driven builds and extensive generated docs.
- test/ contains integration-style tests and target-specific configs, reinforcing that correctness depends on real protocol and platform interactions rather than unit logic alone.
Main entry points: handler.go Adapters · box.go Box core · inbound.go Protocols · router.go Router
Components 22
Core runtime
Primary orchestration and daemon entry points.
- Box core · Top-level engine and shared runtime glue.
box.go - CLI daemon · Main command surface for running, checking, generating, and tooling.
cmd/sing-box/main.go - Daemon control · Daemon lifecycle and started-service control boundary.
daemon/started_service.proto
Config model
External options and shared constants used to assemble runtime behavior.
- Options · Typed configuration model for inbounds, outbounds, DNS, routes, services, and transports.
option/options.go - Constants · Protocols, paths, timeouts, OS tags, and cross-cutting enums.
constant/protocol.go - Feature gates · Compile-time capability toggles and platform stubs.
include/registry.go
Composition
Adapters and lifecycle wiring that instantiate subsystems from config.
- Adapters · Registers and instantiates runtime subsystems from config.
adapter/handler.go - Inbound adapters · Listener-side composition for inbound protocols and interceptors.
adapter/inbound/adapter.go - Outbound adapters · Egress-side composition for outbound protocols and selectors.
adapter/outbound/adapter.go - DNS adapters · Builds DNS clients, transports, and routing integration.
dns/transport_adapter.go
Traffic plane
Protocol handlers and transport primitives that process connections.
- Protocols · Concrete inbound/outbound implementations for proxy and tunnel protocols.
protocol/socks/inbound.go - Transports · Protocol-adjacent transport and plugin compatibility layers.
transport/v2ray/transport.go - TLS stack · Reusable TLS, ECH, Reality, uTLS, and transport helpers.
common/tls/client.go - Sniffer · Protocol and payload detection used before routing and dialing.
common/sniff/sniff.go - Ingress · Listeners, redirect/TProxy, pipe listeners, and mux entry points.
common/listener/listener.go
Policy plane
Routing and DNS decision layers.
Platform integration
OS-facing services, interception, and host integration.
- Services · System integrations such as ACME, resolved, OCM/CCM, OOM killer, and SSM API.
service/resolved/service.go - Host hooks · OS-specific proxy settings, Wi-Fi state, redirection, drivers, and process lookup.
common/settings/system_proxy.go
Extensions
Compatibility APIs and embeddable library surfaces.
Connections 25
- CLI daemon → Box core: starts · CLI launches the core engine and runtime modes.
- Daemon control → Box core: controls · Daemon service boundary attaches to the running engine.
- Box core → Adapters: assembles · Core runtime builds subsystem adapters from parsed config.
- Adapters → Options: reads · Adapters consume typed configuration objects.
- Adapters → Inbound adapters: wires · Instantiates inbound listeners and interception entry points.
- Adapters → Outbound adapters: wires · Instantiates outbound and selector components.
- Adapters → DNS adapters: wires · Instantiates DNS transports and resolver managers.
- Adapters → Services: starts · Bootstraps host-facing services and integrations.
- Adapters → Host hooks: binds · Connects platform-specific hooks and settings.
- Inbound adapters → Ingress: accepts · Ingress adapters use listeners, redirection, and TUN/TProxy paths.
- Ingress → Sniffer: annotates · Incoming flows are inspected for protocol and metadata hints.
- Sniffer → Router: feeds · Detected metadata informs routing decisions.
- Router → DNS stack: queries · Route decisions can trigger DNS resolution and fake-IP behavior.
- DNS stack → DNS adapters: uses · DNS stack is built from transport registries and adapters.
- DNS stack → Router: influences · Resolved answers and fake-IP mapping feed later policy decisions.
- Outbound adapters → Protocols: selects · Outbound adapters instantiate concrete protocol handlers.
- Inbound adapters → Protocols: selects · Inbound adapters instantiate concrete protocol handlers.
- Protocols → Transports: encapsulates · Protocol handlers rely on transport variants and plugin compatibility layers.
- Transports → TLS stack: depends on · Transport variants use TLS and dialer infrastructure for remote sessions.
- Protocols → TLS stack: uses · Protocol implementations rely on shared TLS and dial helpers.
- Host hooks → Router: enriches · Process, network, and Wi-Fi state improve rule matching.
- Services → Host hooks: integrates · Services connect to OS facilities such as resolver, proxy, and driver APIs.
- Libbox → Adapters: embeds · Library surface reuses the same adapter/runtime assembly.
- Clash API → Box core: observes · Compatibility API exposes live status and control surfaces.
- V2Ray API → Box core: observes · Compatibility API exposes live stats and control surfaces.