How to set up TON Proxy

TON Proxy bridges HTTP traffic to ADNL. This page covers two setups:

• Forward proxy: browse TON Sites from a conventional browser.
• Reverse proxy: host a TON Site behind an ADNL endpoint. See the reverse proxy overview for the concept.

Forward proxy

Accepts browser HTTP requests on a local port and forwards them to TON Sites over ADNL.

Prerequisites

• rldp-http-proxy binary from a TON monorepo release (v2024.01 or newer) or built from source
• Optional alternative: Tonutils-Proxy (v1.8.0 or newer), a Go client with a GUI and built-in tunnel support
• TON global network configuration file (global.config.json), available from the TON monorepo

Set up rldp-http-proxy

Start the forward proxy:

rldp-http-proxy -p 8080 -c 3333 -C global.config.json

Configure the browser HTTP proxy to 127.0.0.1:8080. TON Sites are reachable by .ton domain names. The full flag list is documented in the TON Proxy reference.

Set up Tonutils-Proxy

Tonutils-Proxy is a Go alternative with built-in support for garlic-routed ADNL tunnels.

Tunnel client configuration

Field	Default	Description
TunnelSectionsNum	1	Number of relay hops
MaxPricePerPacket	0	Maximum nanoTON per packet, 0 = no limit
NodesPoolConfigPath	empty	Path to a JSON file pinning specific relays

The tunnel rebuilds automatically after 45 seconds of inactivity.

Verify the forward proxy

Request a known TON Site through the proxy:

curl --proxy http://127.0.0.1:8080 http://foundation.ton/

A successful response returns HTML content from the TON Foundation site. ps aux | grep rldp-http-proxy (or ps aux | grep tonutils-proxy) confirms the process is running.

Troubleshoot the forward proxy

• Port already in use: another process is bound to port 8080. Change the port with -p <PORT> and update the browser proxy setting accordingly.
• global.config.json not found: the -C flag path must point to the actual file location. Pass the absolute path or run from the directory containing the file.
• .ton domain does not resolve: the proxy connects to the TON DHT on startup. Wait a few seconds after launch, then retry. Check that UDP outbound traffic on port 3333 (or the port set by -c) is not blocked by a firewall.

Reverse proxy

Accepts inbound ADNL connections and forwards HTTP requests to a local web server, enabling hosting for a TON Site.

Prerequisites

• rldp-http-proxy binary from a TON monorepo release (v2024.01 or newer), or tonutils-reverse-proxy binary from the tonutils/reverse-proxy releases (v0.4.0 or newer)
• generate-random-id binary (included in the TON monorepo release archive): required for the rldp-http-proxy key generation step
• global.config.json: available from the TON monorepo
• A public IPv4 address with an open UDP port (default: 3333) reachable from the internet

Use rldp-http-proxy

Step 1: generate an ADNL address

Create a keyring directory and generate a key pair:

mkdir keyring

generate-random-id -m keys -n liteserver

This produces liteserver (private key) and liteserver.pub (public key) in the current directory.

Move the private key into the keyring:

mv liteserver keyring/

The hex-encoded key ID printed by generate-random-id is the ADNL address (<ADNL_ADDRESS>).

Key backup

Back up the keyring directory before exposing the reverse proxy to mainnet traffic.

• Risk: losing the private key means losing the ADNL address permanently; any domain bound to it becomes unreachable.
• Scope: the keyring/ directory and any backup copies.
• Mitigation: store an encrypted backup off-host; set file permissions to 600.
• Environment: validate the full setup on TON Testnet before binding a mainnet domain.

Step 2: start the reverse proxy

rldp-http-proxy -a <PUBLIC_IP>:3333 -L '*' -C global.config.json -A <ADNL_ADDRESS> -d -l <LOG_FILE>

Flag	Description
-a <PUBLIC_IP>:3333	Public IP and UDP port for ADNL connections
-L '*'	Accept requests for any hostname
-C global.config.json	Path to TON global network configuration
-A <ADNL_ADDRESS>	ADNL address generated in step 1
-d	Run as daemon
-l <LOG_FILE>	Path to the log file

The reverse proxy forwards incoming HTTP requests to 127.0.0.1:80 by default. Point a local web server at that address.

Use tonutils-reverse-proxy

Install

Download the latest tonutils-reverse-proxy-linux-amd64 binary from the releases page and make it executable:

chmod +x tonutils-reverse-proxy-linux-amd64

Alternatively, build from source:

git clone https://github.com/tonutils/reverse-proxy.git
cd reverse-proxy
make build

Run the reverse proxy

Start with domain assignment:

./tonutils-reverse-proxy-linux-amd64 --domain <DOMAIN>

On first launch the binary generates an ADNL key pair automatically and prints a QR code linking to a TON DNS configuration transaction. Scan the QR code with a TON wallet to register the ADNL address in the domain record.

DNS record transaction

Setting the site record of a .ton domain is an on-chain transaction that cannot be refunded.

• Risk: signing a QR payload for a wrong ADNL address binds the domain to the wrong endpoint; the gas fee is not refundable, and a second correction transaction is required.
• Scope: the domain owner wallet and the .ton domain record.
• Mitigation: verify the printed ADNL address character-by-character against the reverse proxy logs before confirming in the wallet.
• Environment: TON Mainnet and TON Testnet both charge gas; test on testnet first.

Response headers

The reverse proxy injects two headers into forwarded requests:

Header	Description
X-Adnl-Ip	Client ADNL IP (not the real client IP)
X-Adnl-Id	Client ADNL identity

Assign a domain

After the reverse proxy is running, register the ADNL address in a .ton domain via TON DNS. Set the site record of the domain to the ADNL address of the reverse proxy.

Verify the reverse proxy

Confirm the ADNL address is reachable and DNS is active:

1. Use the forward proxy above and request the .ton domain in a browser to confirm end-to-end routing.
2. Check that the ADNL address is registered in the domain’s site record via a TON DNS lookup tool such as dns.ton.org.
3. Inspect the reverse proxy log (-l <LOG_FILE>) for incoming connection entries to confirm traffic is arriving.

Troubleshoot the reverse proxy

• Firewall blocking UDP: the public UDP port (default 3333) must be open inbound. Verify with nc -u -zv <PUBLIC_IP> 3333 from an external host. Update firewall rules if the port is filtered.
• Private key not loaded: the private key file must reside inside the keyring/ directory and the directory must be in the working directory where rldp-http-proxy is launched. Check that keyring/<KEY_FILE> exists.
• DNS propagation delay: after the on-chain DNS transaction is confirmed, allow up to 60 seconds for the record to propagate across DHT nodes before testing.
• tonutils-reverse-proxy QR code does not appear: ensure the terminal supports block characters. Run with a UTF-8 locale or redirect the output and scan the raw URL printed alongside the QR code.

Related pages

• TON Proxy: how the proxy bridge works
• Reverse proxy overview: reverse proxy concept and use cases
• TON Sites: web services hosted over ADNL
• TON Proxy reference: all CLI flags and configuration fields
• TON DNS: domain registration and record types