# ref1nd/sing-box architecture

> Architecture diagram of the GitHub repository ref1nd/sing-box, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ref1nd/sing-box
- Repository: https://github.com/ref1nd/sing-box

## Overview

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: [`adapter/handler.go`](https://github.com/ref1nd/sing-box/blob/testing/adapter/handler.go) (Adapters), [`box.go`](https://github.com/ref1nd/sing-box/blob/testing/box.go) (Box core), [`protocol/socks/inbound.go`](https://github.com/ref1nd/sing-box/blob/testing/protocol/socks/inbound.go) (Protocols), [`route/router.go`](https://github.com/ref1nd/sing-box/blob/testing/route/router.go) (Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_box["Box core<br/>runtime engine<br/>[box.go]"]
  node_cmd["CLI daemon<br/>entrypoint<br/>[main.go]"]
  node_daemon["Daemon control<br/>grpc control"]
end

subgraph group_config["Config model"]
  node_option["Options<br/>config schema<br/>[options.go]"]
  node_constant["Constants<br/>shared values<br/>[protocol.go]"]
  node_include["Feature gates<br/>build flags<br/>[registry.go]"]
end

subgraph group_compose["Composition"]
  node_adapter["Adapters<br/>composition layer<br/>[handler.go]"]
  node_inbound["Inbound adapters<br/>adapter registry<br/>[adapter.go]"]
  node_outbound["Outbound adapters<br/>adapter registry<br/>[adapter.go]"]
  node_dns_adapter["DNS adapters<br/>adapter registry"]
end

subgraph group_traffic["Traffic plane"]
  node_protocols["Protocols<br/>traffic handlers<br/>[inbound.go]"]
  node_transports["Transports<br/>encapsulation<br/>[transport.go]"]
  node_tls["TLS stack<br/>crypto/networking<br/>[client.go]"]
  node_sniff["Sniffer<br/>inspection<br/>[sniff.go]"]
  node_listener["Ingress<br/>[listener.go]"]
end

subgraph group_policy["Policy plane"]
  node_route["Router<br/>policy engine<br/>[router.go]"]
  node_dns["DNS stack<br/>resolver engine<br/>[router.go]"]
end

subgraph group_platform["Platform integration"]
  node_service["Services<br/>os service<br/>[service.go]"]
  node_platform["Host hooks<br/>platform integration<br/>[system_proxy.go]"]
end

subgraph group_ext["Extensions"]
  node_libbox["Libbox<br/>ffi library<br/>[command.go]"]
  node_clashapi["Clash API<br/>compat api<br/>[server.go]"]
  node_v2rayapi["V2Ray API<br/>compat api<br/>[server.go]"]
end

node_cmd -->|"starts"| node_box
node_daemon -->|"controls"| node_box
node_box -->|"assembles"| node_adapter
node_adapter -->|"reads"| node_option
node_adapter -->|"wires"| node_inbound
node_adapter -->|"wires"| node_outbound
node_adapter -->|"wires"| node_dns_adapter
node_adapter -->|"starts"| node_service
node_adapter -->|"binds"| node_platform
node_inbound -->|"accepts"| node_listener
node_listener -->|"annotates"| node_sniff
node_sniff -->|"feeds"| node_route
node_route -->|"queries"| node_dns
node_dns -->|"uses"| node_dns_adapter
node_dns -->|"influences"| node_route
node_outbound -->|"selects"| node_protocols
node_inbound -->|"selects"| node_protocols
node_protocols -->|"encapsulates"| node_transports
node_transports -->|"depends on"| node_tls
node_protocols -->|"uses"| node_tls
node_platform -->|"enriches"| node_route
node_service -->|"integrates"| node_platform
node_libbox -->|"embeds"| node_adapter
node_clashapi -->|"observes"| node_box
node_v2rayapi -->|"observes"| node_box

click node_box "https://github.com/ref1nd/sing-box/blob/testing/box.go"
click node_cmd "https://github.com/ref1nd/sing-box/blob/testing/cmd/sing-box/main.go"
click node_daemon "https://github.com/ref1nd/sing-box/blob/testing/daemon/started_service.proto"
click node_option "https://github.com/ref1nd/sing-box/blob/testing/option/options.go"
click node_constant "https://github.com/ref1nd/sing-box/blob/testing/constant/protocol.go"
click node_include "https://github.com/ref1nd/sing-box/blob/testing/include/registry.go"
click node_adapter "https://github.com/ref1nd/sing-box/blob/testing/adapter/handler.go"
click node_inbound "https://github.com/ref1nd/sing-box/blob/testing/adapter/inbound/adapter.go"
click node_outbound "https://github.com/ref1nd/sing-box/blob/testing/adapter/outbound/adapter.go"
click node_dns_adapter "https://github.com/ref1nd/sing-box/blob/testing/dns/transport_adapter.go"
click node_route "https://github.com/ref1nd/sing-box/blob/testing/route/router.go"
click node_dns "https://github.com/ref1nd/sing-box/blob/testing/dns/router.go"
click node_protocols "https://github.com/ref1nd/sing-box/blob/testing/protocol/socks/inbound.go"
click node_transports "https://github.com/ref1nd/sing-box/blob/testing/transport/v2ray/transport.go"
click node_tls "https://github.com/ref1nd/sing-box/blob/testing/common/tls/client.go"
click node_sniff "https://github.com/ref1nd/sing-box/blob/testing/common/sniff/sniff.go"
click node_listener "https://github.com/ref1nd/sing-box/blob/testing/common/listener/listener.go"
click node_service "https://github.com/ref1nd/sing-box/blob/testing/service/resolved/service.go"
click node_platform "https://github.com/ref1nd/sing-box/blob/testing/common/settings/system_proxy.go"
click node_libbox "https://github.com/ref1nd/sing-box/blob/testing/experimental/libbox/command.go"
click node_clashapi "https://github.com/ref1nd/sing-box/blob/testing/experimental/clashapi/server.go"
click node_v2rayapi "https://github.com/ref1nd/sing-box/blob/testing/experimental/v2rayapi/server.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_box,node_cmd,node_daemon,node_libbox,node_clashapi,node_v2rayapi toneBlue
class node_option,node_constant,node_include toneAmber
class node_adapter,node_inbound,node_outbound,node_dns_adapter toneMint
class node_protocols,node_transports,node_tls,node_sniff,node_listener toneRose
class node_route,node_dns toneIndigo
class node_service,node_platform toneTeal
```

## Components

### Core runtime

Primary orchestration and daemon entry points.

- [Box core](https://github.com/ref1nd/sing-box/blob/testing/box.go): runtime engine · Top-level engine and shared runtime glue. · `box.go`
- [CLI daemon](https://github.com/ref1nd/sing-box/blob/testing/cmd/sing-box/main.go): entrypoint · Main command surface for running, checking, generating, and tooling. · `cmd/sing-box/main.go`
- [Daemon control](https://github.com/ref1nd/sing-box/blob/testing/daemon/started_service.proto): grpc 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](https://github.com/ref1nd/sing-box/blob/testing/option/options.go): config schema · Typed configuration model for inbounds, outbounds, DNS, routes, services, and transports. · `option/options.go`
- [Constants](https://github.com/ref1nd/sing-box/blob/testing/constant/protocol.go): shared values · Protocols, paths, timeouts, OS tags, and cross-cutting enums. · `constant/protocol.go`
- [Feature gates](https://github.com/ref1nd/sing-box/blob/testing/include/registry.go): build flags · Compile-time capability toggles and platform stubs. · `include/registry.go`

### Composition

Adapters and lifecycle wiring that instantiate subsystems from config.

- [Adapters](https://github.com/ref1nd/sing-box/blob/testing/adapter/handler.go): composition layer · Registers and instantiates runtime subsystems from config. · `adapter/handler.go`
- [Inbound adapters](https://github.com/ref1nd/sing-box/blob/testing/adapter/inbound/adapter.go): adapter registry · Listener-side composition for inbound protocols and interceptors. · `adapter/inbound/adapter.go`
- [Outbound adapters](https://github.com/ref1nd/sing-box/blob/testing/adapter/outbound/adapter.go): adapter registry · Egress-side composition for outbound protocols and selectors. · `adapter/outbound/adapter.go`
- [DNS adapters](https://github.com/ref1nd/sing-box/blob/testing/dns/transport_adapter.go): adapter registry · Builds DNS clients, transports, and routing integration. · `dns/transport_adapter.go`

### Traffic plane

Protocol handlers and transport primitives that process connections.

- [Protocols](https://github.com/ref1nd/sing-box/blob/testing/protocol/socks/inbound.go): traffic handlers · Concrete inbound/outbound implementations for proxy and tunnel protocols. · `protocol/socks/inbound.go`
- [Transports](https://github.com/ref1nd/sing-box/blob/testing/transport/v2ray/transport.go): encapsulation · Protocol-adjacent transport and plugin compatibility layers. · `transport/v2ray/transport.go`
- [TLS stack](https://github.com/ref1nd/sing-box/blob/testing/common/tls/client.go): crypto/networking · Reusable TLS, ECH, Reality, uTLS, and transport helpers. · `common/tls/client.go`
- [Sniffer](https://github.com/ref1nd/sing-box/blob/testing/common/sniff/sniff.go): inspection · Protocol and payload detection used before routing and dialing. · `common/sniff/sniff.go`
- [Ingress](https://github.com/ref1nd/sing-box/blob/testing/common/listener/listener.go): network ingress · Listeners, redirect/TProxy, pipe listeners, and mux entry points. · `common/listener/listener.go`

### Policy plane

Routing and DNS decision layers.

- [Router](https://github.com/ref1nd/sing-box/blob/testing/route/router.go): policy engine · Evaluates traffic metadata and rule sets to select paths. · `route/router.go`
- [DNS stack](https://github.com/ref1nd/sing-box/blob/testing/dns/router.go): resolver engine · DNS client/router plus upstream transport selection and fake-IP handling. · `dns/router.go`

### Platform integration

OS-facing services, interception, and host integration.

- [Services](https://github.com/ref1nd/sing-box/blob/testing/service/resolved/service.go): os service · System integrations such as ACME, resolved, OCM/CCM, OOM killer, and SSM API. · `service/resolved/service.go`
- [Host hooks](https://github.com/ref1nd/sing-box/blob/testing/common/settings/system_proxy.go): platform integration · OS-specific proxy settings, Wi-Fi state, redirection, drivers, and process lookup. · `common/settings/system_proxy.go`

### Extensions

Compatibility APIs and embeddable library surfaces.

- [Libbox](https://github.com/ref1nd/sing-box/blob/testing/experimental/libbox/command.go): ffi library · Embedded/mobile library API with command, profile, telemetry, and tunnel hooks. · `experimental/libbox/command.go`
- [Clash API](https://github.com/ref1nd/sing-box/blob/testing/experimental/clashapi/server.go): compat api · Clash-compatible control, stats, and profile surface. · `experimental/clashapi/server.go`
- [V2Ray API](https://github.com/ref1nd/sing-box/blob/testing/experimental/v2rayapi/server.go): compat api · V2Ray-compatible stats/control surface. · `experimental/v2rayapi/server.go`

## Connections

- 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.
