ppz

module

v0.17.0 Latest Latest Go to latest Published: May 3, 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 (any platform with Go 1.22+):

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

This compiles from source via go install for now; pre-built binaries via GitHub Releases land on every tag (see the Releases tab) — once the release pipeline is wired through end-to-end the install script will switch over to downloading the right artifact for the current OS/arch.

From source:

git clone https://github.com/pipescloud/ppz
cd ppz
make build
# binaries land in ./bin

What's in the box

Binary	Purpose
`ppz`	The user-facing CLI (`ppz source create`, `ppz broadcast`, `ppz read`, `ppz terminal …`).
`ppz-server`	Hosts the org/source/pipe state and embeds a NATS server. Self-hostable; pipescloud.io runs one.
`ppz-desktop`	Local web GUI for browsing pipes.
`ppz-seed`	Bootstraps a server with seed data (test / dev only).
`ppz-natsbootstrap`	Generates the NATS NSC chain (operator + system account).

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
docs/SECRETS.md — secret model

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.