Zoraxy: a Go reverse proxy with a web UI for homelabs

What Zoraxy replaces in a homelab

The README describes Zoraxy as "a general purpose HTTP reverse proxy and forwarding tool. Now written in Go!" The audience is stated just as plainly: standalone mode suits "new owners to homelabs or makers starting growing their web services into multiple servers." That is a specific group. It is not platform teams with a service mesh, and it is not people who enjoy maintaining an Nginx config tree by hand. It is the person who has five containers on one box, wants app.example.com to land on the right one, and does not want to learn a new config language to get there.

The feature list is broad for that scope. HTTP/2 reverse proxying with virtual directories, automatic WebSocket proxying that the README says needs no setup, Basic Auth, alias hostnames, custom headers and load balancing. On top of routing there are redirection rules, TLS with ACME auto-renew, SNI and SAN certificate support, and DNS challenge through the DNS providers listed by the lego project. There is also a stream proxy for TCP and UDP, an integrated uptime monitor, a web SSH terminal, and small utilities such as a CIDR converter, mDNS scanner, Wake-On-Lan, IP scanner and port scanner. Country and IP blacklists and whitelists accept a single IP, CIDR or wildcard.

The honest framing is that Zoraxy bundles an admin panel and a proxy into one process. If you only need the proxy part, you are carrying the UI, the database and the utility pages with it.

How the proxy, config and plugin layer fit together

The repository layout tells you most of the architecture. The Go source lives under src/, the web interface assets ship with it (the primary language on the repository is HTML), and configuration is separated from the binary: the -conf flag defaults to ./conf and the -dbpath flag defaults to ./sys.db. So the process is a single Go binary plus a config directory plus a database file. Moving a Zoraxy install means moving those two things.

The database backend is selectable. The -db flag accepts leveldb, boltdb or auto, and the help text notes that fsdb will be used on unsupported platforms like RISCV. That auto default matters on unusual hardware: you do not get to pick a backend that the platform cannot support, and on RISCV you get the filesystem-backed one whether you wanted it or not.

Routing state is edited through the web UI, not through text files you diff in git. That is the core design decision and it has consequences in both directions. Adding a route is a form submission rather than a config reload, which is why the project can offer an experimental nginx to Zoraxy config converter for people migrating. The cost is that your routing table lives in a database, so reviewing changes means reviewing UI history or the database, not a pull request.

Plugins are a first-class concept: there is a plugin system, an example/plugins/ directory in the repository, and the Global Area Network Controller was moved out of the core into the official plugin repo. The README also marks some areas as community maintained, naming contributors for Forward Auth, Oauth2, ACME DNS challenge, the Docker container list and the changelog.

Installing Zoraxy and routing your first hostname

The fastest path is a release binary. The README links Windows amd64, Linux amd64 and Linux arm64 builds directly, and points to the Releases page for other systems and architectures. On Windows the documented procedure is to download the executable and double click it. On Linux, including Raspberry Pi and other ARM boards, you run the binary and pass a listen port. Port 8000 appears in every example, so treat it as the default you will be changing.

sudo ./zoraxy -port=:8000

After that starts, the admin interface is served on that port and you create the single admin account. The README says standalone mode is the default and behaves "just like a basic home router," and it links a full Getting Started guide on the wiki. For Raspberry Pi it adds one concrete rule: on a Pi 4 or newer pick the arm64 release, and on older Pis use the arm (armv6) build.

If you prefer to build from source, the README requires Go 1.23 or higher and gives these steps.

 git clone https://github.com/tobychui/zoraxy
cd ./zoraxy/src/
go mod tidy
go build

sudo ./zoraxy -port=:8000

Docker users are pointed at the docker/ folder in the repository rather than given a compose file in the README. Once the UI is up, the first real task is adding a proxy rule for a hostname and pointing it at a backend on your network, then issuing a certificate. Before you burn a real Let's Encrypt certificate on a misconfigured hostname, the -acmetestmode flag runs ACME in test/staging mode. The renew check interval is controlled by -autorenew, which defaults to 86400 seconds.

If you already have an authentication proxy in front, Zoraxy can run without its own login.

./zoraxy -noauth=true

The README attaches a warning to this flag: enable no-auth only in a trusted environment or with another authentication management proxy in front.

Where Zoraxy is the wrong tool

The single-admin model is the first real constraint. The README lists "Basic single-admin management mode" and separately mentions an external permission management system for integration. If you need several operators with different levels of access inside Zoraxy itself, that is not what this is. The documented escape hatch is to put your own authentication layer in front and run with -noauth=true, which removes Zoraxy's own gate rather than adding roles to it.

Web SSH is narrower than the feature list suggests. The README states it currently supports only Linux based OSes and lists linux/amd64, linux/arm64, linux/armv6 (experimental) and linux/386 (experimental). On Windows or macOS you do not get that terminal. Loopback connections are refused by default, so connecting to 127.0.0.1 or localhost is rejected for security reasons unless you start with -sshlb=true, which the README frames as a testing and development override.

Maintenance is uneven by the project's own admission. The README has a "Looking for Maintainer" list covering ACME integration (auto-renew and Zoraxy integration), Zoraxy Auth (the built-in basic SSO feature) and the logging module including analysis and attack prevention. A feature listed as seeking a maintainer is a feature whose future is not settled. The ACME DNS challenge, Forward Auth and Oauth2 sections are credited to individual community contributors, which means issue routing depends on those people being available.

Security reporting has a documented detour. The README says that because of recent automated or AI generated advisories, security advisories are no longer accepted directly on GitHub; you are asked to contact the team via Discord, provide your GitHub username, and be assigned an advisory number. That is a friction point worth knowing before you need it. Finally, the nginx to Zoraxy config converter is described as experimental, so a migration from Nginx should be checked rule by rule rather than trusted wholesale.

Zoraxy compared with Traefik, Caddy and Nginx Proxy Manager

The comparison that matters is where the routing configuration lives. Traefik discovers services from labels and provider APIs, so your routing is declared alongside the workloads and moves with them. Zoraxy does the opposite: routes are created in its own UI and stored in its own config and database. If your infrastructure is dynamic and containers appear and disappear, Traefik's model fits better. If your services are a stable set of hosts and ports, Zoraxy's model is less machinery.

Caddy is the closest in spirit on certificates, since both handle ACME automatically, but Caddy's configuration is a text file (or its admin API) with a compact syntax, and Zoraxy's is a web interface backed by a database. That difference decides how you review changes and how you back up. With Caddy you keep a Caddyfile in version control. With Zoraxy you back up the -conf directory and the -dbpath file.

Nginx Proxy Manager is the nearest neighbour in audience: a UI over a proxy for people who do not want to hand-write Nginx. The practical difference is the underlying engine and the extras. Zoraxy is a single Go binary that also ships a stream proxy for TCP and UDP, an uptime monitor, a web SSH terminal and network utilities like mDNS scanning and Wake-On-Lan. Nginx Proxy Manager is a UI in front of Nginx. If you already have Nginx operational knowledge and want that engine underneath, the NPM route keeps your skills relevant. If you want one binary and no Nginx, Zoraxy is the shorter path.

None of these differences are settled by feature counts. They are settled by whether you want your routing in a database, in labels, or in a file.

Licence, upgrades and what maintenance costs you

Zoraxy is licensed under AGPL-3.0. The practical implication is the network clause: if you modify Zoraxy and let users interact with it over a network, the AGPL's source-availability expectations attach to your modified version in a way the GPL's would not for purely local software. Running the unmodified binary for your own services is the ordinary case. If you plan to fork it, embed it in a product, or ship a modified version to customers, read the licence text yourself or get advice from someone qualified to give it. This is not legal advice.

The upgrade story has one documented wrinkle. Among the start parameters is -cfgupgrade, described as "Enable auto config upgrade if breaking change is detected (default true)." That default is doing real work: it means the binary will migrate your configuration when it detects a breaking change, and you should know it exists before you pin a version and then wonder why the config directory changed shape. The -conf and -dbpath flags are what you back up before an upgrade, and they are also what you restore if the upgrade goes wrong.

Release cadence is visible in the tags: v3.3.4-rc2, then v3.3.4-rc3, then v3.3.4, with the last push to the repository on 2026-08-22. That pattern of release candidates before a stable tag tells you the project does not ship straight from main to stable, which is a point in its favour for anyone running it in front of real hostnames. It also means you should decide whether you track stable tags or release candidates, because the README does not document a rollback procedure for a bad upgrade. Your rollback is the copy of conf/ and sys.db you made first.

Editorial conclusion

Adopt Zoraxy if you run a handful of self-hosted services behind one host and want routing, ACME certificates and an uptime monitor in a single binary with a browser UI. Skip it if you need multi-user role separation, since the README describes a basic single-admin management mode, or if you depend on the built-in SSO feature, which is listed as looking for a maintainer. Before committing, verify three things on your own hardware: that your CPU architecture has a release binary or that Go 1.23 or higher builds from source, that port 8000 is free or that you change it with -port, and that your certificate flow works in staging with -acmetestmode before you point real hostnames at it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes