# nicocha30/ligolo-ng architecture

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

- Interactive diagram: https://gitdiagram.com/nicocha30/ligolo-ng
- Repository: https://github.com/nicocha30/ligolo-ng

## Overview

Ligolo-ng is a reverse TCP/TLS tunneling tool: a local network tool sends traffic through a TUN interface, a userland stack translates it into remote connections, and an agent relays those connections to its reachable network. The proxy also manages agent sessions, listeners, interfaces/routes, configuration, and a web/API surface. The README documents the packet-to-agent workflow; source excerpts show session handling and selected component calls. Some command, API, and platform-specific wiring is not fully sampled, so those links are omitted or marked unverified.

Main entry points: [`cmd/proxy/app/app.go`](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/app.go) (CLI and tunnels), [`cmd/proxy/main.go`](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/main.go) (Proxy runtime), [`pkg/proxy/netstack/handlers.go`](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/handlers.go) (TCP UDP ICMP), [`pkg/agent/handler.go`](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/agent/handler.go) (Agent handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime entrypoints"]
  node_agentcmd["Agent runtime<br/>[main.go]"]
  node_proxycmd["Proxy runtime<br/>[main.go]"]
end

subgraph group_sessions["Agent sessions"]
  node_controller["Connection listener<br/>[controller.go]"]
  node_agenthandler["Agent handler<br/>[handler.go]"]
  node_protocol["Packet protocol<br/>[packets.go]"]
  node_relay["Stream relays<br/>[relay.go]"]
  node_agentstate["Agent sessions<br/>[agent.go]"]
  node_tls["TLS certificates<br/>[certmanager.go]"]
end

subgraph group_tunnel["Tunnel datapath"]
  node_tun["TUN interface<br/>[gvisor.go]"]
  node_netstack["Userland stack<br/>[stack.go]"]
  node_flowhandlers["TCP UDP ICMP<br/>[handlers.go]"]
end

subgraph group_management["Proxy management"]
  node_proxyapp["CLI and tunnels<br/>[app.go]"]
  node_webapi["Web and API<br/>[daemon.go]"]
  node_config["Proxy configuration<br/>[config.go]"]
  node_listeners["Agent listeners<br/>[listeners.go]"]
end

subgraph group_platform["Host networking"]
  node_netinfo["Route management<br/>[netinfo.go]"]
  node_ifcommands["Interface commands<br/>[interfaces.go]"]
end

node_tool(("Network tool"))

node_tool -->|"sends packets"| node_tun
node_tun -->|"feeds packets"| node_netstack
node_netstack -->|"dispatches flows"| node_flowhandlers
node_flowhandlers -->|"relays connections"| node_agenthandler
node_agenthandler -->|"encodes messages"| node_protocol
node_agenthandler -->|"starts relays"| node_relay
node_proxycmd -->|"starts listener"| node_controller
node_controller -->|"loads certificates"| node_tls
node_proxycmd -->|"runs commands"| node_proxyapp
node_proxycmd -->|"registers agents"| node_agentstate
node_agentcmd -->|"handles session"| node_agenthandler
node_proxyapp -.->|"manages sessions"| node_agentstate
node_agentstate -->|"requests agent info"| node_protocol
node_proxyapp -->|"starts tunnels"| node_netstack
node_flowhandlers -->|"encodes flows"| node_protocol
node_flowhandlers -->|"relays streams"| node_relay
node_proxyapp -.->|"adds listeners"| node_listeners
node_listeners -->|"sends requests"| node_protocol
node_listeners -->|"forwards sockets"| node_relay
node_proxyapp -->|"uses settings"| node_config
node_proxyapp -->|"manages tunnel interface"| node_netinfo
node_ifcommands -->|"configures routes"| node_netinfo
node_ifcommands -->|"stores interface settings"| node_config
node_proxycmd -.->|"starts API"| node_webapi
node_webapi -->|"updates settings"| node_config

click node_agentcmd "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/agent/main.go"
click node_proxycmd "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/main.go"
click node_controller "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/controller/controller.go"
click node_agenthandler "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/agent/handler.go"
click node_protocol "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/protocol/packets.go"
click node_relay "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/relay/relay.go"
click node_agentstate "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/controller/agent.go"
click node_proxyapp "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/app.go"
click node_webapi "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/daemon.go"
click node_config "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/config/config.go"
click node_listeners "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/listeners.go"
click node_tun "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/tun/gvisor.go"
click node_netstack "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/stack.go"
click node_flowhandlers "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/handlers.go"
click node_netinfo "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netinfo/netinfo.go"
click node_ifcommands "https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/interfaces.go"
click node_tls "https://github.com/nicocha30/ligolo-ng/blob/master/pkg/tlsutils/certmanager.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_agentcmd,node_proxycmd toneBlue
class node_controller,node_agenthandler,node_protocol,node_relay,node_agentstate,node_tls toneAmber
class node_tun,node_netstack,node_flowhandlers toneMint
class node_proxyapp,node_webapi,node_config,node_listeners toneRose
class node_netinfo,node_ifcommands,node_tool toneIndigo
```

## Components

### Runtime entrypoints

- [Agent runtime](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/agent/main.go): `cmd/agent/main.go`
- [Proxy runtime](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/main.go): `cmd/proxy/main.go`

### Agent sessions

- [Connection listener](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/controller/controller.go): `pkg/controller/controller.go`
- [Agent handler](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/agent/handler.go): `pkg/agent/handler.go`
- [Packet protocol](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/protocol/packets.go): `pkg/protocol/packets.go`
- [Stream relays](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/relay/relay.go): `pkg/relay/relay.go`
- [Agent sessions](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/controller/agent.go): `pkg/controller/agent.go`
- [TLS certificates](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/tlsutils/certmanager.go): `pkg/tlsutils/certmanager.go`

### Tunnel datapath

- [TUN interface](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/tun/gvisor.go): `pkg/proxy/netstack/tun/gvisor.go`
- [Userland stack](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/stack.go): `pkg/proxy/netstack/stack.go`
- [TCP UDP ICMP](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netstack/handlers.go): `pkg/proxy/netstack/handlers.go`

### Proxy management

- [CLI and tunnels](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/app.go): `cmd/proxy/app/app.go`
- [Web and API](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/daemon.go): `cmd/proxy/app/daemon.go`
- [Proxy configuration](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/config/config.go): `cmd/proxy/config/config.go`
- [Agent listeners](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/listeners.go): `pkg/proxy/listeners.go`

### Host networking

- [Route management](https://github.com/nicocha30/ligolo-ng/blob/master/pkg/proxy/netinfo/netinfo.go): `pkg/proxy/netinfo/netinfo.go`
- [Interface commands](https://github.com/nicocha30/ligolo-ng/blob/master/cmd/proxy/app/interfaces.go): `cmd/proxy/app/interfaces.go`

### Other components

- **Network tool**

## Connections

- Network tool → TUN interface: sends packets
- TUN interface → Userland stack: feeds packets (evidence: `pkg/proxy/netstack/stack.go`)
- Userland stack → TCP UDP ICMP: dispatches flows (evidence: `pkg/proxy/netstack/stack.go`)
- TCP UDP ICMP → Agent handler: relays connections
- Agent handler → Packet protocol: encodes messages (evidence: `pkg/agent/handler.go`)
- Agent handler → Stream relays: starts relays (evidence: `pkg/agent/handler.go`)
- Proxy runtime → Connection listener: starts listener (evidence: `cmd/proxy/main.go`)
- Connection listener → TLS certificates: loads certificates (evidence: `pkg/controller/controller.go`)
- Proxy runtime → CLI and tunnels: runs commands (evidence: `cmd/proxy/main.go`)
- Proxy runtime → Agent sessions: registers agents (evidence: `cmd/proxy/main.go`)
- Agent runtime → Agent handler: handles session (evidence: `cmd/agent/main.go`)
- CLI and tunnels → Agent sessions: manages sessions
- Agent sessions → Packet protocol: requests agent info (evidence: `pkg/controller/agent.go`)
- CLI and tunnels → Userland stack: starts tunnels (evidence: `cmd/proxy/app/app.go`)
- TCP UDP ICMP → Packet protocol: encodes flows (evidence: `pkg/proxy/netstack/handlers.go`)
- TCP UDP ICMP → Stream relays: relays streams (evidence: `pkg/proxy/netstack/handlers.go`)
- CLI and tunnels → Agent listeners: adds listeners
- Agent listeners → Packet protocol: sends requests (evidence: `pkg/proxy/listeners.go`)
- Agent listeners → Stream relays: forwards sockets (evidence: `pkg/proxy/listeners.go`)
- CLI and tunnels → Proxy configuration: uses settings (evidence: `cmd/proxy/app/app.go`)
- CLI and tunnels → Route management: manages tunnel interface (evidence: `cmd/proxy/app/app.go`)
- Interface commands → Route management: configures routes (evidence: `cmd/proxy/app/interfaces.go`)
- Interface commands → Proxy configuration: stores interface settings (evidence: `cmd/proxy/app/interfaces.go`)
- Proxy runtime → Web and API: starts API
- Web and API → Proxy configuration: updates settings (evidence: `cmd/proxy/app/daemon.go`)
