Installation: Linux, macOS, and Windows

QuickZTNA’s client is a single binary, ztna, on Linux, macOS, and Windows. The installer downloads the right build for your OS/architecture, verifies its checksum, installs it to /usr/local/bin (or the Windows program directory), and sets up a system service. Kernel TUN is used on every platform (Linux /dev/net/tun, Windows Wintun, macOS utun).

Before you install

• Administrator access on the device (to register a service and create the network interface).
• A QuickZTNA account — sign up at login.quickztna.com. The Free plan covers 100 devices and 3 users.
• Outbound HTTPS to login.quickztna.com (TCP/443). Peer-to-peer data uses UDP where possible and transparently falls back to an encrypted relay (DERP) when UDP is blocked. No inbound ports.

Linux & macOS — one-line install

curl -fsSL https://login.quickztna.com/install.sh | sh

The script detects your OS and architecture, resolves the latest version via the control plane, downloads the matching archive from https://login.quickztna.com/api/releases/…, verifies its SHA-256 checksum, installs ztna to /usr/local/bin, and registers the system service (systemd on Linux, launchd on macOS). Then authenticate:

ztna login

ztna login opens a browser for SSO sign-in; approve the device and you’re connected. (Other auth methods — GitHub, Google, a pre-auth key, or interactive terminal login — are on the CLI reference.)

Headless / fleet (auth key, no browser)

For servers, containers, and mass rollouts, generate a pre-auth key in the dashboard and pass it to the installer as an environment variable — the client registers itself non-interactively:

curl -fsSL https://login.quickztna.com/install.sh | ZTNA_AUTH_KEY=tskey-auth-xxx sh

On Linux the installer writes the key into the service’s environment so the daemon self-registers on start; on a fresh device it prints either “Connected” or “Registered. Waiting for admin approval” depending on your org’s onboarding policy.

Windows

irm https://login.quickztna.com/install.ps1 | iex

This downloads the Windows bundle (a .zip containing ztna.exe, the service binary, and the Wintun driver), installs it, and registers the QuickZTNA Windows service. Then run ztna login (or set $env:ZTNA_AUTH_KEY before the install command for headless onboarding).

Manual / offline download

If piping a script to a shell isn’t an option, download the archive directly. The release artifacts live under:

https://login.quickztna.com/api/releases/v<version>/ztna-<version>-<os>-<arch>.tar.gz     # linux, darwin
https://login.quickztna.com/api/releases/v<version>/ztna-<version>-windows-<arch>.zip     # windows

A matching .sha256 is published next to each archive — verify it before installing. Then place the binary on your PATH and register the service:

sudo install -m0755 ztna /usr/local/bin/ztna
sudo ztna install            # sets up the systemd/launchd service
ztna login

Headless servers & containers

The headless path is the same binary with a pre-auth key. The client needs the CAP_NET_ADMIN capability and access to /dev/net/tun to bring up its kernel interface, and a persisted state directory so it keeps its identity across restarts (otherwise it re-registers as a new device each start). Use ZTNA_AUTH_KEY to register non-interactively, set a structured name with --hostname, and pre-classify the device with tags via ztna up --advertise-tags tag:prod,tag:server.

Verifying your install

ztna version          # confirm the installed version
ztna status           # connection state, your tailnet IP, peers
ztna peers            # peers and whether each is direct or relayed

If you have a second device on the network, confirm reachability with your system’s normal tools (e.g. ping <peer-tailnet-ip> or ssh user@<peer>), using the names/IPs from ztna status.

Updating

ztna update --check   # see if a newer version is available
ztna update           # download and apply

Enable unattended updates with ztna set --auto-update. Re-running the install script also upgrades in place.

Uninstalling

sudo ztna logout      # remove this device from your organization (no ghost in the device list)
sudo ztna uninstall   # stop + remove the service and clean up local config

On Windows, uninstall from Apps & features (or run ztna uninstall).

Restricted networks

QuickZTNA needs only outbound HTTPS to login.quickztna.com. Peer-to-peer connections use UDP NAT traversal where possible; when UDP is blocked, traffic falls back to an encrypted relay (DERP) in one of our two regions (Bangalore and Frankfurt) — no operator action and no inbound ports required. For an explicit HTTP proxy, set the standard HTTPS_PROXY environment variable.

What’s next

• Quickstart — from install to your first connection.
• Managing devices — tags, approval, removing departed devices, fleet rollouts.
• CLI reference — every ztna command.
• Troubleshooting — the issues we see most often.