ZTM: a zero trust mesh built on HTTP/2 tunnels

HTTP/2 tunnels as the transport

ZTM is network infrastructure software for running a decentralised network, built upon HTTP/2 tunnels, and it can run on any sort of IP networks, with LANs, containerised networks, and the Internet given as examples. The project description calls it a privacy first, open source, decentralised, end to end encrypted software defined network.

The choice of HTTP/2 as the substrate is the whole design in one line. Rather than inventing a new tunnel protocol, ZTM uses a protocol that most middleboxes will let through, and the README makes the performance argument in the simplest possible terms: HTTP/2 multiplexing is fast, and Pipy is fast, in the phrase of the README, like C++ fast.

The set of capabilities it claims is short and specific. Network connectivity across internet gateways and firewalls. TLS encrypted communication channels. Certificate based authentication and access control. Decentralised application publishing and deployment. Decentralised file discovery and data sharing.

The scale claim is wide, from a two node personal network connecting a home and a workplace to a ten thousand node enterprise network connecting offices and branches across the globe. The examples given are concrete: remote access to a home computer from anywhere, sharing documents, pictures, and videos inside a group without a large platform in the middle, and private peer to peer data transfer without the fear of eavesdropping.

What is not in that list is worth noticing too. There is no mention of a managed service, a control plane hosted by a vendor, or a per user pricing model. The model is that you run the pieces yourself.

PipyJS is the engine, and the policy layer

ZTM is written in PipyJS, a JavaScript dialect designed for Pipy, which the README describes as an open source programmable proxy software and, in the features section, as a general purpose network scripting engine. Pipy itself lives in a separate repository, and the ZTM repository carries it as a submodule.

That choice explains most of what is distinctive about ZTM. A proxy engine is a component that sits in the middle of connections and decides what to do with them, and a general purpose one lets you write that decision in code. So the security policy of a ZTM network is not a configuration file with checkboxes, it is a script, and the README states that by using PipyJS the security policy can be easily customised to meet the requirements in your organization.

The four feature claims in the README follow from that. Fast, because HTTP/2 multiplexing and Pipy are fast. Secure, because all traffic is encrypted by TLS and carries identities through certificates, with the policy layer on top. Highly customizable and programmable, because Pipy is a general purpose network scripting engine. Portable, because the engine is a self contained binary.

The portability claim is concrete. For the CPU you can choose x86, ARM, MIPS, RISC-V, or LoongArch, and for the operating system Linux, Windows, macOS, FreeBSD, or Android. The README also carries badges for the desktop application, which is built with Tauri, and for Rust and C++ and Vite in the toolchain.

The trade is the one that comes with programmability. A policy you write is a policy you maintain, and it is a piece of code that has to be correct for the network to be private.

The Hub issues a permit file, and that is the trust anchor

The topology in the README is the clearest description of the design. A common setup consists of three nodes, one running the Hub and two running Agents that wish to communicate with each other.

The Hub keeps its state in a file at ~/.ztm/ztm-hub.db, and each Agent keeps its own state in ~/.ztm/ztm.db. The Hub is the component that has to be reachable: the diagram puts it in a data centre, with HTTPS on port 8888 on both sides, and shows the Agents behind firewalls in a home and a workplace.

So the flow is that the Hub generates a file named root.json that allows endpoints to join the mesh, and the endpoints are added by using that generated permit file. An endpoint is defined in the README simply as a computer running in various network environments with access to the internet.

That is a point worth pressing on, because the project is described as decentralised and the diagram has a central piece. The decentralisation is in what the Hub does and does not do. It hands out a permit, and it is where the agents register, but the traffic between agents is end to end encrypted and does not pass through the Hub, and the certificate based authentication is what actually decides who is allowed to join a mesh. The Hub is a distribution point for the permit rather than a relay for your data.

It is still a real dependency, though. The Hub needs a public address, and the permit file is a credential that has to be delivered to each endpoint, so the security of the mesh depends on how that file travels.

Building a three node mesh

The quick start is short, and the commands are worth following exactly, since several of the details matter.

The Hub lives on a Linux box in the cloud with a public IP address and a public TCP port. The README uses 1.2.3.4 and port 8888 as the example, and the Hub is started with a listen address, a names list, and the permit file to generate.

ztm start hub --listen 0.0.0.0:8888 --names 1.2.3.4:8888 --permit root.json

Two things to note. The command installs a service to systemd, so you might need sudo to run it. And the address in the names list is the address the agents will use to reach the Hub, which is why it has to be the public one rather than 0.0.0.0.

Once the Hub is running, a root.json file has been generated, and that is the permit that lets endpoints join.

Each endpoint then starts an Agent.

ztm start agent

The Windows caveat is explicit in the README: starting as a system service is not supported yet, so on Windows you have to run the agent in the foreground with the run subcommand instead.

That is the entire setup for a working mesh of three nodes, and the point worth taking from it is how little of it there is. There is no certificate authority to install and no client configuration to distribute by hand; the permit file is the artefact that moves.

The README also documents shell completion, which is a small convenience that makes the CLI easier to live with. For bash, the completion script is written to a directory you create first.

mkdir -p ~/.local/share/ztm/completions
ztm completion bash > ~/.local/share/ztm/completions/ztm.bash
source ~/.local/share/ztm/completions/ztm.bash

The zsh variant writes a file whose name starts with an underscore into the same directory and then adds that directory to your fpath.

mkdir -p ~/.local/share/ztm/completions
ztm completion zsh > ~/.local/share/ztm/completions/_ztm
fpath=(~/.local/share/ztm/completions $fpath)
autoload -U compinit && compinit

Two packaging forms, one binary

There are two ways to get ZTM, and the difference between them is about packaging rather than about features.

The first is the official build releases, which come in two forms. One is the CLI tool packaged as a SEA, a Single Executable Application, which means one file you download and run. The other is the desktop application, which wraps up the CLI tool and provides a GUI for desktop environments. The README points at the release page for the latest binary, and at the Build document for people who want their own build from source.

The repository layout shows how the pieces are separated. There is an agent directory, a hub directory, a cli directory, a ca directory for the certificate authority side, a gui directory for the desktop application, an extensions directory, a docs directory, a build directory, and a scripts directory. The Pipy engine is present as a submodule, and there are separate build scripts for the full build and for a CLI only build, as shell and as a Windows batch file, plus a build directory for the desktop application.

The desktop application being a wrapper around the CLI is the important design point. It means the graphical tool and the command line tool are the same program with different faces, so a team can script the CLI in automation and use the GUI when a person is involved, without the two disagreeing about state.

The documentation set in the repository is small and points at separate files: Architecture & Concepts, the CLI reference, ZT-App for the desktop application, the Agent API, and Build. The Agent API document is the one to look at if you want to automate against a running agent, and the architecture document is the one to read before you write a policy.

What the project does not settle

There are gaps in the documentation that matter for an infrastructure tool, and it is better to name them than to discover them later.

The first is the trust model in practice. The README says traffic is encrypted and authenticated with certificates, and it says a permit file lets endpoints join, but the repository does not document, in the part available here, how certificates are issued, rotated, or revoked. The ca directory in the source tree suggests there is a certificate authority component, and the agent API document is likely where the operations live, but a reader of the README alone cannot tell you what happens when a laptop is lost.

The second is the decentralisation claim versus the topology. A Hub with a public IP and a public TCP port is a single point that every agent depends on for joining, and the setup guide says the Hub is usually a cloud hosted Linux virtual machine. If that machine is down, existing agents keep their connections, but new ones cannot join, and the guide does not describe a multi-Hub or Hub failover arrangement.

The third is the scale claim. A ten thousand node enterprise network is a stated target rather than a documented configuration, and the quick start stops at three nodes. There is no reference configuration, no sizing guidance beyond the diagram, and no description of how the Hub behaves at high agent counts.

On the other hand, the thing that is usually vague in this category is documented well. The exact command to start a Hub, the exact port, the exact state file locations, the fact that a permit file is generated, and the Windows service limitation are all spelled out, and that is more than most projects in this space tell you.

On maintenance, the project is not archived, the last push was on 2026-08-14, and the releases are v2.0.0 on 2026-02-13, v1.0.4 on 2026-01-30, and a v1.0.4 release candidate in September 2025. The version 2.0.0 with the one before it on a two major version gap suggests the 2.0 line is where the project is settling. The licence is Apache-2.0, which is permissive and, for a network component you run yourself, easy to live with.

Editorial conclusion

ZTM fits a team that wants a private network across sites, a home and an office, or a set of machines it controls, and that is willing to run a Hub on a public server and to manage certificates and permit files as part of that setup. It does not fit a deployment that cannot open a public TCP port, and it does not fit Windows environments that need the agent to run as a service. Verify first that you have a Linux box with a public IP and a free TCP port for the Hub, that the client machines can reach it through their firewalls on the port the Hub listens on, and that the PipyJS policy layer is something your team is prepared to own, since the programmability that makes ZTM flexible is the same thing you have to maintain.

Frequently asked questions

Official sources

1. flomesh-io/ztm on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases