WhiteDNS Wizard: a Cloudflare-first provisioner for a 3x-ui/Xray stack

The gap WhiteDNS Wizard fills between a bare VPS and a working proxy

Standing up 3x-ui by hand means several unrelated jobs: creating A records, deciding which hostnames can sit behind the Cloudflare proxy and which cannot, obtaining a certificate that covers the DNS-only names, installing the panel and its database, and then producing import strings that clients can actually paste. WhiteDNS Wizard bundles those steps into one interactive flow that runs on your machine and reaches the VPS over SSH. The README describes it as a provisioning wizard for setting up a managed 3x-ui/Xray VPN stack, and the repository layout backs that up: cmd/ holds the entry point, internal/ and pkg/ hold the logic, and scripts/ sits alongside them.

The intended user is someone who has a VPS and a Cloudflare-managed domain but does not want to assemble the stack piece by piece. The wizard's opinion is visible in its defaults. Proxied WebSocket TLS profiles go through Cloudflare; protocols the Cloudflare proxy cannot carry get DNS-only records; and a separate set of Tor-exit variants is generated so a user can import those instead. That last choice is unusual. Most installers stop at one working config; this one ships two parallel families and expects you to pick per client.

How the init flow sequences Cloudflare, certificates and Docker

The flow is ordered, and the order matters. According to the README, init validates the Cloudflare token, detects the zone, creates or updates DNS records, sets the Cloudflare SSL mode to strict, creates an Origin CA certificate for proxied profiles, issues a public ACME wildcard certificate for the DNS-only TLS profiles, installs or repairs the Docker 3x-ui and PostgreSQL stack, adds a private Tor sidecar for outbound routing, replaces only WhiteDNS-managed inbounds and outbounds after confirmation, then prints and saves client import strings.

Two mechanisms are worth calling out. First, token validation is not a local check: the wizard calls the Cloudflare endpoint GET /client/v4/accounts/<account-id>/tokens/verify using the account ID you typed. That is why a correct token paired with the wrong account ID fails. Second, certificate issuance has a fallback path. If the machine running the wizard cannot complete the TLS connection to Let's Encrypt, the README says WhiteDNS retries the same DNS-01 issuance from the VPS over SSH, using an installed lego binary when one is present or a short-lived goacme/lego:v4.24.0 container otherwise. The lego dependency is also pinned in go.mod as github.com/go-acme/lego/v4 v4.24.0, so the same library is used on both sides of that fallback.

The DNS side is deliberately split. Records for vpn, trojan, panel, direct, hy2, reality, ss and the six tor-* hostnames are all A records pointing at the same VPS IP, but only vpn and trojan are proxied. Everything else is DNS-only, because the Cloudflare proxy cannot carry the protocols those hostnames serve. ACME adds temporary _acme-challenge TXT records during issuance, and the wildcard request for *.<domain> means one challenge covers the DNS-only TLS names rather than one per host.

Installing WhiteDNS Wizard and running the first setup

The README gives a build-from-source path rather than a package or release download. Go 1.24.2 is the version declared in go.mod. Build the binary from the repository root:

go build -o whitedns ./cmd/whitedns

Then run it with no arguments. The root command opens the menu, and the README points at entry 0 for the setup flow:

./whitedns

0) Init setup

Before you start, create the Cloudflare token the wizard expects. The README points at Manage Account > Account API Tokens > Create Token and the Edit zone DNS template, then asks you to add permissions beyond the template. The final set listed is:

DNS & Zones / DNS: Read + Edit
DNS & Zones / Zone: Read
DNS & Zones / Zone Settings: Edit
Cache & Performance / Zone SSL & Certificates: Edit

The wizard then prompts for the Cloudflare account ID, the API token, the domain, the VPS IPv4 address, and SSH details (host, user, key or passphrase, or password). There is no documented dry-run mode, so the first run against a production VPS is the real one. The README's troubleshooting table maps each failure to a missing permission: a zone lookup failure usually means Zone: Read is absent or the token is not scoped to the selected domain, and an SSL mode strict failure points at Zone Settings: Edit.

The twelve generated profiles and what each one assumes

The wizard produces import strings in two families. The direct family covers VLESS WS on 443 over the vpn hostname through the Cloudflare proxy, VLESS WS on 8443 over the trojan hostname, Hysteria2 on 443/udp, direct VLESS TCP TLS on 2087, Reality TCP Vision on 2083, and Shadowsocks 2022 on 8388. The Tor family mirrors the same transports on different ports: VLESS WS Tor on 2097, VLESS WS 8443 Tor on 2098, Hysteria2 Tor on 2099/udp, direct VLESS Tor on 2100, Reality TCP Vision Tor on 2101, and Shadowsocks Tor on 8390.

Port allocation is the part to check before adopting. The README's own table shows 443 and 8443 used twice, once for the direct family and once for the Tor family, but the Tor entries are on distinct hostnames with distinct ports, so the collision is only apparent. Reality is the exception worth noting: the README states that Reality profiles currently use either apple.com or docker.com as the saved SNI and Reality target, rather than a hostname you own. That is a fixed choice, not a configurable one, and it means the Reality profile's camouflage is whatever those two domains present at the time.

Normal TLS profiles keep their own hostnames as SNI so public certificate validation works, which is why the wildcard certificate matters. If you only intend to use the proxied profiles, the DNS-only half of the setup is overhead you are paying for.

Where WhiteDNS Wizard is the wrong tool

The init flow replaces WhiteDNS-managed inbounds and outbounds after confirmation. The word to hold onto is managed: the README frames the replacement as scoped, but it does not document rollback, and it does not enumerate what counts as managed. If you have spent time tuning an existing 3x-ui instance, the honest position is that the README does not tell you how to undo a replacement, so the safe assumption is that you cannot. Back up the panel database yourself before running init on a live server.

The Cloudflare dependency is structural, not incidental. A nameserver delegation problem is called out explicitly in the troubleshooting table, with the note that it is not fixed by deleting or adding rows in the Cloudflare DNS records table. If your domain is not delegated to Cloudflare, the wizard cannot proceed regardless of how good your token is. Similarly, the token permission set is broad: Zone Settings: Edit and Zone SSL & Certificates: Edit are account-level reach, not scoped to a single record type.

Reality is the third soft spot. Because the SNI is fixed to apple.com or docker.com, the profile is not tailored to your traffic, and there is no documented way to substitute your own target. If you need Reality pointed at a domain you control, this wizard makes that harder than a manual 3x-ui setup would.

WhiteDNS Wizard compared with installing 3x-ui by hand

The alternative is the manual route: install 3x-ui yourself, point your own DNS records at the VPS, and run certbot or lego for certificates. The difference is where the state lives. Manual setup leaves every record, certificate and inbound as an independent artifact you created and can edit independently. WhiteDNS Wizard collapses that into a project with encrypted local secrets and repeatable reset and repair flows, which is the trade: less per-piece control, more repeatability when you rebuild.

The certificate handling is the clearest divergence. A manual setup typically issues one certificate per hostname or runs a single wildcard challenge you configure yourself. WhiteDNS requests a wildcard for *.<domain> and adds _acme-challenge TXT records automatically, then falls back to issuing from the VPS if your local network cannot reach Let's Encrypt. That fallback is a real advantage on networks with restrictive egress, and it is the kind of thing a manual setup usually leaves you to debug alone.

The Tor sidecar has no direct equivalent in a stock 3x-ui install. You would add the outbound routing yourself. Having six Tor-routed profiles generated alongside the direct ones is the feature most likely to decide the choice, in either direction.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-07-24, and v1.4.3 was released the same day. v1.4.2 and v1.4.1 both landed in June 2026, so the recent release cadence is a few weeks apart, but the repository is not archived and the README does not describe a support policy or a compatibility guarantee for 3x-ui versions. The stack pins PostgreSQL and a Docker-based 3x-ui install, and the wizard installs or repairs it, which means upgrades are largely the project's problem rather than yours until you need to diverge.

The licence is not stated in the README or in the repository's top-level entries. That is a practical problem, not a legal footnote: without a declared licence you do not have clear terms for redistribution or for bundling the binary into your own tooling. Treat the licence question as unresolved until you find a statement in the repository, and do not assume a permissive default.

The dependency surface is moderate. go.mod lists Cloudflare's cloudflare-go/v7, go-acme/lego/v4, miekg/dns, cobra, bubbletea, bubbles, lipgloss and yaml.v3 as direct requirements, with a longer indirect list. Each of those is a moving part in an upgrade, and the Cloudflare API client in particular tracks an API that changes.

Editorial conclusion

Adopt WhiteDNS Wizard if you are starting from a bare VPS and want the twelve profiles it generates: Cloudflare-proxied WebSocket TLS, DNS-only direct protocols, and Tor-routed variants of each, with DNS, certificates and the Docker stack handled in one pass. Do not adopt it if your 3x-ui instance already carries hand-tuned inbounds and outbounds, because the init flow replaces WhiteDNS-managed inbounds after confirmation, and the README does not document rollback for that step. Before running it, verify three things: that your Cloudflare token carries DNS: Read + Edit, Zone: Read, Zone Settings: Edit and Zone SSL & Certificates: Edit; that your registrar's nameservers actually point to Cloudflare; and that the domain you pass is the zone the token is scoped to, since a subdomain project may need the parent zone.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. WhiteDNS/WhiteDNS-Wizard on GitHub