# docs

One command installs `piper` and `piperd` on any platform and lands you on a real upgrade channel: apt on Debian-family Linux, Homebrew on macOS, verified binaries everywhere else.

Register an app, deploy a directory that holds a Dockerfile, and open it at `http://<name>.piper.localhost` — all on the box, with no login and no relay.

Bare `piper` in a terminal opens a full-screen control surface: apps, deploys, logs, boxes, and the login and GitHub wizards, all interactive. Every subcommand stays scriptable and unchanged.

On the box itself the CLI needs no login. To drive the box from a laptop on the same network, open the control API off loopback, mint a token on the box, and log the CLI in once.

One command on the box signs you in with GitHub and claims the box on the public relay: your apps get `https://<hash>-<you>.public.getpiper.dev` URLs with no port forwarding and no domain of your own.

Any control command can target one of your relay-connected boxes from anywhere, by the base domain `piper login` printed. Requests travel relay → tunnel → box; your relay credential never reaches the box.

Once a box has joined the relay, a `git push` builds and publishes an app. The hosted relay holds one shared GitHub App on everyone's behalf, so there is nothing to create: `piper login` installs it on the repos you choose.

Serve every app under a domain you own with one wildcard cert, or attach one domain to one app with a single CNAME. TLS ends on the box either way; the relay only splices bytes by SNI.

A box with a public IP can terminate its own HTTPS on `:443` and skip the relay's splice: point DNS at the box, keep the relay for login and webhooks — or run with no relay at all.

Every `piper` verb, its flags, and what it does. Each synopsis is the exact usage line the binary prints, and `test/docs` fails when a verb changes and this page does not.

Every `PIPER_*` variable each binary reads, with its default and what it does. `test/docs` fails when a binary reads a name this page does not list.

piperd's HTTP control plane: every route the `piper` CLI, the TUI, and the dashboard use, with request and response shapes and the error statuses each handler returns. `test/docs` fails when a route is registered without a heading here.