Hanzo Zrok

Hanzo Zrok is a zero-trust sharing platform built on top of Hanzo ZT (OpenZiti). It lets users securely share web services, files, and network resources through firewalls and NAT without any networ...

Overview

Hanzo Zrok is a zero-trust sharing platform built on top of Hanzo ZT (OpenZiti). It lets users securely share web services, files, and network resources through firewalls and NAT without any network configuration changes. Single binary. Public and private sharing modes. Self-hostable. Fork of openziti/zrok.

Why Hanzo Zrok?

Instant sharing: zrok share public localhost:8080 exposes a local service with a public URL

Zero config: Works through firewalls, NAT, corporate networks -- no port forwarding

Private sharing: Share services only with specific zrok users, no public internet exposure

File sharing: Turn any directory into a shareable network drive (--backend-mode drive)

End-to-end encrypted: All traffic encrypted via Hanzo ZT overlay, even from zrok servers

Self-hostable: Run your own zrok instance from Raspberry Pi to enterprise scale

Multi-protocol: HTTP/HTTPS, TCP, UDP, and WebDAV file sharing

Tech Stack

Language: Go (backend + CLI), Node.js (web console UI)

Go module: github.com/openziti/zrok/v2 (upstream module path, not yet rebranded)

Go version: 1.25.3

Binary: zrok2 (symlinked to zrok)

UI: Node.js 22 (React-based web console + agent UI)

Database: SQLite (embedded, via mattn/go-sqlite3 with CGO)

API: OpenAPI-generated REST server (go-openapi suite, Swagger spec in specs/)

TUI: Charm stack (bubbletea, bubbles, lipgloss) for terminal UI

Container base: openziti/ziti-cli:latest (includes Ziti CLI tools)

Release: GoReleaser (darwin, linux-amd64/arm64/armhf/armel, windows)

OpenZiti Dependencies

Zrok is an application layer built on top of the OpenZiti networking fabric:

openziti/sdk-golang v1.2.8 -- Go SDK for Ziti network access

openziti/channel/v4 v4.2.37 -- Message channels over Ziti

openziti/edge-api v0.26.48 -- Edge management API client

openziti/identity v1.0.116 -- Identity/certificate management

openziti/transport/v2 v2.0.194 -- Transport layer

openziti/ziti v1.6.0 -- Core Ziti runtime

openziti/foundation/v2 -- Common utilities

OSS Base

Fork of openziti/zrok. Repo: hanzoai/zrok. License: Apache 2.0. The go.mod still references the upstream module path. Branding partially applied (README, Dockerfile labels reference Hanzo, but internal module paths remain OpenZiti).

When to use

Sharing a local web app or API with teammates without deploying

Exposing development servers through corporate firewalls

Sharing files/directories as a network drive

Private service-to-service connectivity between zrok-enabled users

Self-hosting a sharing platform for your organization

Replacing ngrok/Cloudflare Tunnel with a zero-trust alternative

Hard requirements

Hanzo ZT network (or OpenZiti network) for the overlay fabric

Go 1.25+ and Node.js 22+ to build from source

CGO enabled (SQLite requires it)

zrok account or self-hosted zrok controller instance

Quick reference

Item	Value
Binary	`zrok2` (aliased `zrok`)
Go module	`github.com/openziti/zrok/v2`
Container	`ghcr.io/hanzoai/zrok`
Base image	`openziti/ziti-cli:latest`
License	Apache 2.0
API spec	`specs/` (OpenAPI/Swagger)
SDKs	Go, Node.js, Python
Database	SQLite (embedded)
Repo	`github.com/hanzoai/zrok`

One-file quickstart

# Install zrok
# (download binary or build from source)

# Create account and enable environment
zrok invite
zrok enable

# Share localhost:8080 publicly
zrok share public localhost:8080

# Share a directory as a network drive
zrok share public --backend-mode drive ~/Documents

# Share privately with other zrok users
zrok share private localhost:3000

Go SDK

package main

import (
    "github.com/openziti/zrok/v2/sdk/golang/sdk"
)

func main() {
    root, _ := sdk.LoadRoot()

    // Create a private share
    shr, _ := sdk.CreateShare(root, &sdk.ShareRequest{
        BackendMode: sdk.TcpTunnelBackendMode,
        ShareMode:   sdk.PrivateShareMode,
    })

    // Listen for connections
    listener, _ := sdk.NewListener(shr.Token, root)
    defer listener.Close()

    // Accept and handle connections...
}

Self-host with Docker Compose

# docker/compose/zrok-instance/
# Contains full self-hosted zrok instance setup
# See: docker/compose/zrok-instance/README.md

Build from source

# Build UI
cd ui && npm ci && npm run build && cd ..
cd agent/agentUi && npm ci && npm run build && cd ..

# Build binary
CGO_ENABLED=1 go build -tags sqlite_foreign_keys \
  -o zrok2 ./cmd/zrok2/

Core Concepts

Architecture

+------------------+     +-------------------+     +------------------+
|  zrok Client     |     |  zrok Controller  |     |  Hanzo ZT Fabric |
|                  |     |                   |     |                  |
|  zrok share      |---->|  REST API         |---->|  Controller      |
|  zrok access     |     |  Account mgmt     |     |  Routers         |
|  zrok reserve    |     |  Share mgmt       |     |  Smart routing   |
|                  |     |  Metrics/limits    |     |  E2E encryption  |
+------------------+     +-------------------+     +------------------+
                                |
                         +------+------+
                         |   SQLite    |
                         |   (state)   |
                         +-------------+

Mode	Description	Use Case
`public`	Anyone with the URL can access	Dev sharing, demos
`private`	Only zrok users with explicit access	Internal services
`reserved`	Persistent share with stable token	Long-running services

Backend Modes

Mode	Description
`proxy`	HTTP reverse proxy to local service (default)
`web`	Static file server
`drive`	WebDAV file sharing (network drive)
`tcpTunnel`	Raw TCP tunnel
`udpTunnel`	Raw UDP tunnel
`caddy`	Caddy web server with custom config
`socks`	SOCKS5 proxy

Directory Structure

cmd/zrok2/              # Main binary entrypoint
controller/             # zrok controller (API server, share/access management)
agent/                  # zrok agent (daemon, background shares)
  agentUi/              # Agent web UI (Node.js)
endpoints/              # Backend mode implementations (proxy, web, drive, tunnel)
environment/            # Environment/identity management
drives/                 # WebDAV drive implementation
sdk/
  golang/               # Go SDK with examples
  nodejs/               # Node.js SDK
  python/               # Python SDK
rest_client_zrok/       # Generated REST API client
rest_model_zrok/        # Generated REST API models
rest_server_zrok/       # Generated REST API server
specs/                  # OpenAPI/Swagger specifications
tui/                    # Terminal UI (Charm stack)
ui/                     # Web console UI (Node.js/React)
docker/
  compose/
    zrok-instance/      # Self-hosted instance compose
    zrok-private-access/
    zrok-private-share/
    zrok-public-reserved/
  images/               # Docker image definitions
build/                  # Build scripts
canary/                 # Canary testing
etc/                    # Configuration templates
website/                # Documentation website
nfpm/                   # Linux package definitions (deb, rpm)

Relationship to Hanzo ZT

Zrok is the application layer on top of Hanzo ZT (the network fabric):

Hanzo ZT (hanzoai/zt) = network overlay fabric (controller, routers, tunnelers, SDKs)

Hanzo Zrok (hanzoai/zrok) = sharing platform that uses ZT for secure connectivity

Zrok controller creates ZT services, policies, and configurations automatically

Users never need to interact with ZT directly -- zrok abstracts it away

Relationship to Hanzo Tunnel

Hanzo Tunnel (hanzoai/tunnel) = WebSocket-based agent bridge for bot/dev control plane

Hanzo Zrok (hanzoai/zrok) = OpenZiti-based sharing platform for network services

Different repos, different purposes, different protocols

Hanzo Tunnel uses plain WSS; Zrok uses the ZT zero-trust overlay

Troubleshooting

Issue	Cause	Solution
CGO errors on build	Missing C compiler	Install `gcc` and `libc6-dev`
SQLite errors	CGO_ENABLED=0	Must build with `CGO_ENABLED=1`
Share fails	No ZT network	Ensure zrok controller has ZT fabric configured
"not enabled"	Environment not initialized	Run `zrok enable` first
Docker build fails	Wrong platform	Use `--platform linux/amd64`

hanzo/hanzo-zt.md - Hanzo ZT zero-trust network fabric (underlying network layer)

hanzo/hanzo-tunnel.md - WebSocket-based agent bridge (different component)

hanzo/hanzo-network.md - Hanzo network infrastructure

hanzo/hanzo-platform.md - PaaS platform

On this page