hanzo-zt

Hanzo ZT is the zero-trust network overlay fabric for Hanzo's secure networking.

Hanzo ZT - Zero-Trust Network Fabric

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-zrok.md, hanzo/hanzo-tunnel.md, hanzo/hanzo-k8s.md

Overview

Hanzo ZT is the zero-trust network overlay fabric for Hanzo's secure networking. Fork of OpenZiti. Provides a programmable mesh network with identity-based access control, end-to-end encryption, dark services, and smart routing. All executables (controller, router, tunnel) built from a single repo. Runs on hanzo-k8s.

When to use

Zero-trust networking between services (no open ports)
Secure tunneling for remote access to K8s services
Dark services that have no public endpoints
mTLS/PKI-based identity for service-to-service auth
End-to-end encrypted connections (not just TLS termination)

Hard requirements

ZT Controller must be running for fabric management
ZT Router provides mesh connectivity
All clients provisioned with certificates -- no anonymous access
PKI managed by ZT's built-in certificate authority

Quick reference

| Item | Value | |------|-------| | Go module | github.com/hanzozt/zt/v2 | | Go version | 1.25.3 | | Version | 2.0 | | License | Apache 2.0 | | Upstream | OpenZiti | | Repo | github.com/hanzoai/zt | | K8s manifests | universe/infra/k8s/zt/ | | Components | controller, router, tunnel | | Storage | BoltDB (bbolt), Raft for HA | | PKI | Built-in CA and identity management | | API | OpenAPI-generated REST |

Architecture

 ZT Controller
 (management API)
 |
 +--------+--------+
 | |
 ZT Router ZT Router
 (edge) (fabric)
 | |
 +------+------+ +-----+-----+
 | | | | |
 Tunnel Tunnel SDK Dark Dark
 (client)(client) Service Service

Key concepts

| Concept | Description | |---------|-------------| | Controller | Management plane. Stores policies, identities, services. REST API. | | Router | Data plane. Mesh routing between endpoints. Edge + fabric roles. | | Tunnel | Client-side agent. Intercepts traffic, routes through fabric. | | Dark service | No open ports. Connects outbound to fabric. Invisible to port scanners. | | Identity | X.509 certificate-based. Provisioned per client/service. | | Service | Named endpoint accessible through the fabric. | | Service policy | Controls which identities can access which services. |

Core packages (hanzozt namespace)

| Package | Version | Purpose | |---------|---------|---------| | hanzozt/foundation/v2 | v2.0.86 | Utilities, logging, config | | hanzozt/channel/v4 | v4.3.4 | Secure message channels | | hanzozt/edge-api | v0.26.52 | Edge management API | | hanzozt/identity | v1.0.125 | Identity and cert management | | hanzozt/sdk-golang | v1.4.1 | Go SDK for ZT network access | | hanzozt/transport/v2 | v2.0.209 | Transport layer (TCP, TLS, WS) | | hanzozt/storage | v0.4.37 | BoltDB-based storage | | hanzozt/dilithium | v0.3.5 | Post-quantum transport |

Quickstart

# Initialize PKI
hanzozt pki create ca --ca-name "Hanzo ZT CA"
hanzozt pki create intermediate --ca-name "Hanzo ZT CA"

# Start controller
hanzozt controller run --config controller.yaml

# Start router
hanzozt router run --config router.yaml

# Create identity for a client
hanzozt edge create identity device my-laptop
hanzozt edge enroll --jwt my-laptop.jwt --out my-laptop.json

# Create a dark service
hanzozt edge create service my-api
hanzozt edge create terminator my-api --router fabric-router --binding sdk

# Create service policy (who can access)
hanzozt edge create service-policy my-api-access Dial \
 --identity-roles "#my-team" \
 --service-roles "@my-api"

K8s deployment

# universe/infra/k8s/zt/
apiVersion: apps/v1
kind: Deployment
metadata:
 name: zt-controller
 namespace: hanzo
spec:
 replicas: 1
 template:
 spec:
 containers:
 - name: controller
 image: ghcr.io/hanzoai/zt-controller:latest
 ports:
 - containerPort: 1280 # Management API
 - containerPort: 6262 # Control plane

Integration with zrok

Hanzo zrok (fork of OpenZiti's zrok) provides user-facing tunnel sharing on top of the ZT fabric:

# Share a local service through ZT fabric
zrok share public localhost:3000

# Access a shared service
zrok access private <share-token>

See hanzo/hanzo-zrok.md for details.

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Identity enrollment fails | JWT expired | Generate new JWT with hanzozt edge create enrollment | | Service unreachable | Service policy missing | Create Dial policy for the identity | | Router not connecting | Controller unreachable | Check controller address in router config | | Tunnel not intercepting | Wrong service config | Verify intercept.v1 config matches service name |

Related Skills

hanzo/hanzo-zrok.md -- Zero-trust sharing platform
hanzo/hanzo-tunnel.md -- WebSocket tunnel bridge
hanzo/hanzo-k8s.md -- K8s infrastructure
hanzo/hanzo-ingress.md -- Public ingress (ZT is for private)

Last Updated: 2026-03-23 Category: Hanzo Ecosystem Related: zero-trust, networking, openziti, pki, mtls, dark-services Prerequisites: PKI concepts, networking basics