Introduction

WaterWall is a modular, chain-based tunneling framework. It lets you build network paths by connecting small nodes together in JSON configuration files.

A WaterWall chain can be as simple as a TCP port forward:

TcpListener -> TcpConnector

Or it can combine multiple transport, protocol, encryption, multiplexing, and packet-processing layers:

TcpListener -> MuxClient -> VlessClient -> TlsClient -> TcpConnector

The same design can also be used for packet-oriented workflows, such as TUN interfaces, WireGuard-style paths, raw packet processing, and packet-to-stream bridges.

How WaterWall Works

WaterWall configurations are built from nodes.

Each node has a focused job:

Node role	Examples
Accept incoming traffic	TcpListener, UdpListener, TunDevice
Connect to an outside destination	TcpConnector, UdpConnector, UdpStatelessSocket
Transform or protect traffic	TlsClient, EncryptionClient, MuxClient, VlessClient
Route or inspect traffic	Router, SniffRouter, LoggerTunnel
Bridge packet and stream models	PacketsToStream, StreamToPackets, PacketsToConnection

You connect nodes with next fields in a JSON config. Traffic moves upstream through the chain, and responses move back downstream through the same chain.

Because nodes are composable, you can start with a small working setup and add features one layer at a time.

Configuration Model

WaterWall uses two levels of configuration:

File	Purpose
core.json	Starts the runtime, configures logging/workers/DNS, and lists config files to load.
Node config files	Define the actual chains and node settings.

Example core.json:

{
  "misc": {
    "workers": 4,
    "ram-profile": "server",
    "mtu": 1500,
    "try-enabling-bbr": true,
    "libs-path": "libs/"
  },
  "dns": {
    "domain-strategy": "prefer-ipv4"
  },
  "configs": [
    "configs/server.json"
  ]
}

Example chain config:

{
  "name": "simple-forward",
  "nodes": [
    {
      "name": "entry",
      "type": "TcpListener",
      "settings": {
        "address": "0.0.0.0",
        "port": 8080
      },
      "next": "exit"
    },
    {
      "name": "exit",
      "type": "TcpConnector",
      "settings": {
        "address": "example.com",
        "port": 80
      }
    }
  ]
}

Where to Start

Start with the Users Manual:

1. Installation
2. Part 1: Core Settings
3. Part 2: Networking Basics
4. Part 3: Config Files and Chains
5. Part 4: Choosing Nodes

After that, use the Node Reference to look up the exact settings for each node you want to use.

If you want to extend WaterWall itself, read the developer guides after you are comfortable with normal chain configuration.

Why WaterWall?

Modular by Design

WaterWall does not force every deployment into one fixed proxy shape. You can compose listeners, connectors, protocol nodes, encryption nodes, packet nodes, and routing nodes into the shape your network actually needs.

Configuration First

Most usage is driven by JSON files. You can build and adjust chains without writing C code.

Stream and Packet Support

WaterWall is not limited to ordinary TCP streams. It can also work with packet-oriented paths and bridge packets through stream transports when a topology requires it.

Runtime-Oriented Implementation

The core is written in C and designed around asynchronous networking, worker threads, buffer pools, and reusable tunnel components.

What WaterWall Is Not

WaterWall is not a single prebuilt VPN profile or one-click proxy preset. It is a toolkit for building network paths. That flexibility is powerful, but it also means you should understand the chain you are configuring.

For a first deployment, keep the chain small, verify it works, then add nodes one at a time.