ppz

module

v0.17.9 Latest Latest Go to latest Published: May 4, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pipescloud/ppz

Links

Open Source Insights

README ¶

ppz

Pipes for agents — private, instant, durable interprocess and internet communications.

ppz is an open-source tool for streaming pipes between agents, processes, and machines. It pairs a CLI + daemon on the user's side with a server that runs NATS / JetStream as the transport.

Hosted ppz is available at pipescloud.io. It's built on this Apache-2.0 core and adds proprietary hosted-only features (security, scalability, billing, team management, ops tooling). The OSS code here is fully self-hostable.

Install

Quick (linux / macOS, amd64 / arm64):

curl -fsSL https://raw.githubusercontent.com/pipescloud/ppz/main/install.sh | bash

Detects your OS + arch, downloads the matching pre-built tarball from the latest GitHub Release, verifies the sha256, and drops the binaries into ~/.local/bin. No Go toolchain required.

By default you get the CLI client: ppz + ppz-desktop (local web GUI). Self-hosters who want to run their own server can opt into the server bundle:

PPZ_INCLUDE_SERVER=1 curl -fsSL .../install.sh | bash
# adds: ppz-server, ppz-natsbootstrap

Other knobs: PPZ_VERSION=v0.17.0 to pin a tag, PPZ_INSTALL_DIR=/usr/local/bin to change the target directory.

From source (requires Go 1.22+):

git clone https://github.com/pipescloud/ppz
cd ppz
make build      # binaries → ./bin/
make install    # ./bin/* → ~/.local/bin/ (same path as install.sh)

make install lands in ~/.local/bin to match the install.sh curl one-liner — running either flow always overwrites the same files, so there's no shadowing risk if you mix them. Override with INSTALL_BIN=/path/to/dir.

What's in the box

Binary	Audience	Purpose
`ppz`	CLI users (default)	The user-facing CLI (`ppz source create`, `ppz broadcast`, `ppz read`, `ppz terminal …`).
`ppz-desktop`	CLI users (default)	Local web GUI for browsing pipes.
`ppz-server`	Self-hosters (`PPZ_INCLUDE_SERVER=1`)	Hosts the org/source/pipe state and embeds a NATS server. pipescloud.io runs one.
`ppz-natsbootstrap`	Self-hosters (`PPZ_INCLUDE_SERVER=1`)	One-shot helper that mints an ephemeral NATS NSC chain (operator + account JWTs) for a fresh server. Production usually pulls these from a secret manager instead.
`ppz-seed`	Source / e2e only	Populates the OSS test fixtures (`foo`/`bar` users, `alpha`/`beta` orgs). Built from source by the compose harness — not published in release tarballs.

Docs

docs/AUTH-V2.md — auth design (GitHub OAuth + per-org NATS account JWTs)
docs/WIRE.md — wire protocol reference (subjects, error codes, retention semantics)
docs/ERRORS.md — error code catalogue

A self-hosting / deployment guide is on the way — track issues for progress.

Tests

make test           # Go unit tests
make e2e            # full Docker-Compose integration suite
make e2e-filter F='broadcast/*'   # subset

Releasing

Tags are minted automatically on each merge to main from Conventional Commits in the PR title / commit subjects:

Prefix	Bump
`feat:` / `feat(scope):`	minor
`fix:` / `fix(scope):`	patch
`feat!:` / `<type>!:` / `BREAKING CHANGE:` in body	major
`chore:`, `docs:`, `refactor:`, `test:`, `ci:`, etc.	no tag

The highest bump level seen in the new commit range wins. Tagging is just tagging — it does not publish binaries. To cut a distribution, manually dispatch the Release workflow (Actions → Release → Run workflow) and pick the tag. That's when goreleaser builds the matrix and attaches the archives to the GitHub Release.

Manual tagging via make tag {patch|minor|major} is still available for special cases.

License

Apache 2.0. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mock-github command mock-github — a minimal stand-in for the GitHub OAuth + user endpoints, used by the e2e compose stack to test ppz-server's /auth/github/* flow without leaving the network.	mock-github — a minimal stand-in for the GitHub OAuth + user endpoints, used by the e2e compose stack to test ppz-server's /auth/github/* flow without leaving the network.
ppz command
ppz-desktop command
ppz-natsbootstrap command ppz-natsbootstrap mints an ephemeral NSC chain (Operator + Account + System Account + Account signing key) and prints the four env vars ppz-server reads at boot.	ppz-natsbootstrap mints an ephemeral NSC chain (Operator + Account + System Account + Account signing key) and prints the four env vars ppz-server reads at boot.
ppz-seed command
ppz-server command
internal
cli Package cli is the entrypoint for `ppz`.	Package cli is the entrypoint for `ppz`.
cliproto Package cliproto holds the contracts shared by the CLI, daemon, server, and desktop: error/exit codes, stdout printers, and IPC types.	Package cliproto holds the contracts shared by the CLI, daemon, server, and desktop: error/exit codes, stdout printers, and IPC types.
clock Package clock returns the current time, honoring PPZ_TEST_CLOCK if set.	Package clock returns the current time, honoring PPZ_TEST_CLOCK if set.
daemon Package daemon implements the long-lived ppz daemon: IPC server, on-disk state, NATS connection, and HTTP client to ppz-server.	Package daemon implements the long-lived ppz daemon: IPC server, on-disk state, NATS connection, and HTTP client to ppz-server.
db Package db owns the postgres connection pool, migrations, and per-table repositories.	Package db owns the postgres connection pool, migrations, and per-table repositories.
desktop Package desktop is the headless / dump-state half of ppz-desktop.	Package desktop is the headless / dump-state half of ppz-desktop.
envelope Package envelope is the JSON shape of every message published on <org_id>.<handle>.broadcast (per WIRE.md §3).	Package envelope is the JSON shape of every message published on <org_id>.<handle>.broadcast (per WIRE.md §3).
natsauth Package natsauth implements Auth V2 Phase 3: decentralized NATS auth via per-Account JWTs (the "NSC model" — see docs/AUTH-V2.md §Phase 3).	Package natsauth implements Auth V2 Phase 3: decentralized NATS auth via per-Account JWTs (the "NSC model" — see docs/AUTH-V2.md §Phase 3).
natsubj Package natsubj builds and parses the ppz subject grammar	Package natsubj builds and parses the ppz subject grammar
seed Package seed provisions the deterministic test fixture: two organisations (alpha, beta) and three plaintext API keys (key-alpha, key-alpha2, key-beta).	Package seed provisions the deterministic test fixture: two organisations (alpha, beta) and three plaintext API keys (key-alpha, key-alpha2, key-beta).
server Package server runs the ppz HTTP API + GUI + embedded NATS.	Package server runs the ppz HTTP API + GUI + embedded NATS.
thirdparty/vt10x Package terminal is a vt10x terminal emulation backend, influenced largely by st, rxvt, xterm, and iTerm as reference.	Package terminal is a vt10x terminal emulation backend, influenced largely by st, rxvt, xterm, and iTerm as reference.
version Package version exposes the build-time version + sha to the CLI's `ppz version` verb.	Package version exposes the build-time version + sha to the CLI's `ppz version` verb.