# sagernet/sing-box architecture

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

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

## Overview

sing-box is a universal proxy platform. Its principal workflow is configuring network entry points and proxy endpoints, then routing traffic through protocol handlers and transports; DNS and service/API capabilities complement that flow. The graph preserves those major runtime areas and the daemon/mobile-facing interfaces visible in the tree. Evidence is limited: the README gives only the product description, and sampled source/index references support some links but not a complete startup or traffic pipeline; unverified connections are dashed.

Main entry points: [`route/router.go`](https://github.com/sagernet/sing-box/blob/testing/route/router.go) (Traffic router), [`protocol/masque/server.go`](https://github.com/sagernet/sing-box/blob/testing/protocol/masque/server.go) (VPN endpoints), [`box.go`](https://github.com/sagernet/sing-box/blob/testing/box.go) (Box runtime), [`experimental/clashapi/server.go`](https://github.com/sagernet/sing-box/blob/testing/experimental/clashapi/server.go) (Clash API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_config["Configuration options<br/>[options.go]"]
  node_cli["CLI commands<br/>[cmd_run.go]"]
  node_core["Box runtime<br/>[box.go]"]
end

subgraph group_traffic["Traffic handling"]
  node_inbound["Inbound manager<br/>[manager.go]"]
  node_router["Traffic router<br/>[router.go]"]
  node_outbound["Outbound manager<br/>[manager.go]"]
  node_dns["DNS transports"]
end

subgraph group_protocols["Protocols and transports"]
  node_endpoints["VPN endpoints<br/>[server.go]"]
  node_protocols["Protocol handlers<br/>[server.go]"]
  node_transports["Transport servers<br/>[server.go]"]
end

subgraph group_services["Services and APIs"]
  node_clash["Clash API<br/>[server.go]"]
  node_serviceapi["Service APIs<br/>[server.go]"]
end

subgraph group_platform["Platform interfaces"]
  node_daemon["Desktop daemon<br/>[server.go]"]
  node_libbox["Native client bridge<br/>[command_client.go]"]
end

node_user(("Network user"))

node_user -.->|"defines settings"| node_config
node_user -.->|"runs commands"| node_cli
node_cli -.->|"starts runtime"| node_core
node_config -.->|"configures"| node_core
node_core -.->|"starts"| node_inbound
node_inbound -.->|"dispatches traffic"| node_router
node_router -.->|"selects proxy"| node_outbound
node_router -.->|"uses DNS"| node_dns
node_protocols -.->|"implements endpoint"| node_endpoints
node_endpoints -->|"uses HTTP server"| node_transports
node_endpoints -->|"uses router"| node_outbound
node_clash -->|"serves proxy routes"| node_router
node_clash -->|"serves DNS routes"| node_dns
node_daemon -->|"configures bridge"| node_libbox
node_daemon -.->|"hosts services"| node_serviceapi

click node_config "https://github.com/sagernet/sing-box/blob/testing/option/options.go"
click node_cli "https://github.com/sagernet/sing-box/blob/testing/cmd/sing-box/cmd_run.go"
click node_core "https://github.com/sagernet/sing-box/blob/testing/box.go"
click node_inbound "https://github.com/sagernet/sing-box/blob/testing/adapter/inbound/manager.go"
click node_router "https://github.com/sagernet/sing-box/blob/testing/route/router.go"
click node_outbound "https://github.com/sagernet/sing-box/blob/testing/adapter/outbound/manager.go"
click node_dns "https://github.com/sagernet/sing-box/blob/testing/dns/transport_manager.go"
click node_endpoints "https://github.com/sagernet/sing-box/blob/testing/protocol/masque/server.go"
click node_protocols "https://github.com/sagernet/sing-box/blob/testing/protocol/openvpn/server.go"
click node_transports "https://github.com/sagernet/sing-box/blob/testing/transport/http/server.go"
click node_clash "https://github.com/sagernet/sing-box/blob/testing/experimental/clashapi/server.go"
click node_serviceapi "https://github.com/sagernet/sing-box/blob/testing/service/api/server.go"
click node_daemon "https://github.com/sagernet/sing-box/blob/testing/experimental/boxdd/server.go"
click node_libbox "https://github.com/sagernet/sing-box/blob/testing/experimental/libbox/command_client.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_config,node_cli,node_core,node_user toneBlue
class node_inbound,node_router,node_outbound,node_dns toneAmber
class node_endpoints,node_protocols,node_transports toneMint
class node_clash,node_serviceapi toneRose
class node_daemon,node_libbox toneIndigo
```

## Components

### Runtime and configuration

- [Configuration options](https://github.com/sagernet/sing-box/blob/testing/option/options.go): `option/options.go`
- [CLI commands](https://github.com/sagernet/sing-box/blob/testing/cmd/sing-box/cmd_run.go): `cmd/sing-box/cmd_run.go`
- [Box runtime](https://github.com/sagernet/sing-box/blob/testing/box.go): `box.go`

### Traffic handling

- [Inbound manager](https://github.com/sagernet/sing-box/blob/testing/adapter/inbound/manager.go): `adapter/inbound/manager.go`
- [Traffic router](https://github.com/sagernet/sing-box/blob/testing/route/router.go): `route/router.go`
- [Outbound manager](https://github.com/sagernet/sing-box/blob/testing/adapter/outbound/manager.go): `adapter/outbound/manager.go`
- [DNS transports](https://github.com/sagernet/sing-box/blob/testing/dns/transport_manager.go): `dns/transport_manager.go`

### Protocols and transports

- [VPN endpoints](https://github.com/sagernet/sing-box/blob/testing/protocol/masque/server.go): `protocol/masque/server.go`
- [Protocol handlers](https://github.com/sagernet/sing-box/blob/testing/protocol/openvpn/server.go): `protocol/openvpn/server.go`
- [Transport servers](https://github.com/sagernet/sing-box/blob/testing/transport/http/server.go): `transport/http/server.go`

### Services and APIs

- [Clash API](https://github.com/sagernet/sing-box/blob/testing/experimental/clashapi/server.go): `experimental/clashapi/server.go`
- [Service APIs](https://github.com/sagernet/sing-box/blob/testing/service/api/server.go): `service/api/server.go`

### Platform interfaces

- [Desktop daemon](https://github.com/sagernet/sing-box/blob/testing/experimental/boxdd/server.go): `experimental/boxdd/server.go`
- [Native client bridge](https://github.com/sagernet/sing-box/blob/testing/experimental/libbox/command_client.go): `experimental/libbox/command_client.go`

### Other components

- **Network user**

## Connections

- Network user → Configuration options: defines settings
- Network user → CLI commands: runs commands
- CLI commands → Box runtime: starts runtime
- Configuration options → Box runtime: configures
- Box runtime → Inbound manager: starts
- Inbound manager → Traffic router: dispatches traffic
- Traffic router → Outbound manager: selects proxy
- Traffic router → DNS transports: uses DNS
- Protocol handlers → VPN endpoints: implements endpoint
- VPN endpoints → Transport servers: uses HTTP server (evidence: `protocol/masque/server.go`)
- VPN endpoints → Outbound manager: uses router
- Clash API → Traffic router: serves proxy routes (evidence: `experimental/clashapi/server.go`)
- Clash API → DNS transports: serves DNS routes (evidence: `experimental/clashapi/server.go`)
- Desktop daemon → Native client bridge: configures bridge (evidence: `experimental/boxdd/server.go`)
- Desktop daemon → Service APIs: hosts services
