openZro

Getting Started

This page walks an admin from a fresh openZro deployment to two connected peers and a working access policy. About 10 minutes of hands-on time.

openZro is self-hosted only — you operate the management server. If you don't have one yet, follow the Self-Hosting Quickstart first (~15 minutes) and then come back here.

1. Sign in to your dashboard

Open the dashboard URL in a browser (https://<your-management>.example.com/). You'll be redirected to your identity provider's sign-in page — openZro has no user database of its own, every account lives in your IdP (Dex, Authentik, Keycloak, Okta, Microsoft Entra, Google Workspace, Auth0, JumpCloud, Zitadel, or any OIDC-compliant provider).

openZro IdP SSO and MFA

After successful authentication you land on the dashboard's Peers page. The first sign-in seeds a default account record, an All group, and a permissive Default Policy that lets every peer reach every other peer — you'll tighten this in step 4.

2. Add your first peer

The dashboard's primary action is the Add Peer button (top right of the Peers page). It opens a modal with one tab per platform:

  • Linux (Debian / Ubuntu / RHEL / Rocky / Fedora / Arch)
  • macOS (Homebrew or .pkg installer)
  • Windows (.msi installer)
  • Docker (single-container quickstart)

Pick your platform, copy the install command into a terminal on the device you want to enroll, and run it:

# Debian / Ubuntu — see the modal for other distros
curl -fsSL https://pkg.openzro.io/openzro-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/openzro-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/openzro-archive-keyring.gpg] \
https://pkg.openzro.io/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/openzro.list > /dev/null
sudo apt-get update && sudo apt-get install -y openzro

Then bring the client up:

sudo openzro up --management-url https://<your-management>.example.com

The CLI opens a browser tab pointed at your IdP. Authenticate with the same account you used in step 1 — the device shows up in the dashboard's Peers list under your user, with a 100.x.y.z address from openZro's overlay subnet.

For full per-OS install details see Install openZro.

3. Add a second peer (headless / Linux server)

Headless devices (servers, VMs, Raspberry Pi, CI runners) can't go through the browser-auth flow in step 2. Use a setup key instead: a long-lived token that pre-authenticates a peer and auto-assigns it to one or more groups.

In the dashboard:

  1. Open Setup Keys in the sidebar.
  2. Click Add Setup Key.
  3. Pick Reusable (the key works for many enrollments) or One-off (single-use), set an expiration, and select which groups new peers using this key should auto-join.
  4. Copy the generated key — it's shown once.

On the headless device, install openZro the same way as step 2, then enroll using the key:

sudo openzro up --setup-key <YOUR_SETUP_KEY>

The peer appears in Peers within seconds, tagged with whatever groups the key assigned.

For details on setup-key options (revocation, ephemeral peers, scoped expiration), see Register Machines using Setup Keys.

4. Verify the connection and inspect access control

Both peers are now in the same overlay. Pick the IP openZro assigned to your second peer (from the Peers list — it's a 100.x.y.z address) and from your first peer's terminal:

ping 100.74.76.17

You should see successful replies — the Default Policy that the dashboard seeded on first login is what makes this work.

To see the policy, open Access Control → Policies. The default rule allows All → All on every protocol/port. Disable that policy and the ping immediately starts timing out; re-enable it and traffic flows again. This is the simplest demo of how openZro mediates peer-to-peer access — every connection is gated by a policy, and policies reference groups (which peers belong to via setup-key assignment or manual edits in the dashboard).

For the full access-control model (policies, groups, posture checks), see Manage Network Access.

5. (Optional) Expose a private subnet via a routing peer

A routing peer is an openZro client running on a machine inside a private network (office LAN, VPC, home network) that forwards traffic from openZro peers to internal IPs that don't run openZro themselves — file servers, printers, RDS instances, internal APIs, etc.

Quick sketch:

  1. Install openZro on a host that lives inside the private network (steps 2 or 3 above).
  2. In the dashboard, open Networks → Add Network.
  3. Define a Network Resource — either a single host (10.10.5.5) or an entire subnet (10.10.0.0/16).
  4. Assign the resource to your routing peer (the host from step 1).
  5. Add a policy that lets the source group (e.g. your laptops) reach this resource.

Remote peers automatically learn the route via openZro's control plane and forward matching traffic through the routing peer.

For the full walkthrough — including high-availability setups with multiple routing peers per resource — see Networks → Use Cases.

Where to go next

  • Manage Peers — approval workflow, peer detail view, lazy connections, SSH.
  • Access Control — groups, policies, posture checks, MDM/EDR integrations.
  • Networks — routing peers, network resources, DNS routes, exit nodes.
  • DNS — magic DNS for peer names, custom nameservers per route.
  • CLI reference — every flag for openzro up, openzro status, openzro down, etc.

Stay in touch