Getting started

Developers have all seen a port conflict error like this one:

Error: listen EADDRINUSE: address already in use :::3000

Port Zero solves this by giving every process or Docker container a stable domain name instead of a port you have to remember. You use it the same way whether you’re running a plain process or a container: set every port to 0 so the OS picks a free one, then start your program with the PZ_TUNNEL environment variable.

1. Install

macOS (Homebrew):

brew tap PortZeroNetwork/portzero
brew install portzero

Linux:

curl -fsSL https://portzero.net/install.sh | sh

Windows:

Download the latest .msi from the GitHub releases page.

2. See it work in one command

portzero demo

This starts the daemon if needed, runs a tiny built-in web server on port 0 with PZ_TUNNEL=hello.portzero.local:80, and opens http://hello.portzero.local in your browser once it’s reachable. No examples to clone, no runtime dependencies. Press Ctrl+C to stop it.

3. Start the daemon

portzero start

This opens the PortZero app — a desktop app showing daemon and tunnel health, the HTTPS toggle, daemon controls, and the bundled examples. Reopen it anytime from the system tray icon’s Open PortZero item, or run portzero start --no-browser to start the daemon without opening it.

4. Tag your own process or container

Set PZ_TUNNEL to a full domain name before you launch the program, and bind its listener to port 0 so the OS picks a free port:

PZ_TUNNEL=myapp.portzero.local:80 python3 -m http.server 0
  • A hostname ending in .portzero.local is a Local tunnel — free, open source, reachable only from this machine.
  • A hostname ending in .tunnel.portzero.cloud is a Cloud tunnel — reachable from the internet, requires portzero login and a subscription.

Open http://myapp.portzero.local in your browser. See Tunnels & PZ_TUNNEL for the full syntax, and Examples for ready-to-run apps in several languages.

5. Check status

portzero status

Shows whether the daemon is running, which tunnels are active, and the connection state.

Next steps