Build your own

The seam is not gated by anything

It is MIT, it lives in core, and it is the code that runs in your Worker. Restricting it would make you can build your own client against your own Worker untrue.

Register a key you generated yourself

pithy dashboard connect --public-key <file> --issuer <url> --kind <agent|script> --purpose "<what it does>"

No dashboard involved — connecting without a browser is the whole procedure — and every route works exactly the same way. Registering takes a signed-in session, so the connection names who authorized it, and --kind and --purpose say what your client is and what it is for. Your Worker stamps that kind onto every control-plane audit row your client’s calls write.

Rotating without one is your own call to make, literally

Register the successor with a signed POST /control-plane/keys, using the key you are replacing — exactly the append-prove-expire order a managed connection follows.

connect --public-key registers a first key and refuses a successor while one is live, naming that call.

Two reasons, and both matter. The CLI has no private half to sign with. And doing it for you would take the registration out of your own audit trail — the append is a signed management call, and a signed management call is a row in your trail.

Or hold no key at all: trust the workload’s identity

A client that runs unattended — in CI, a container, a job — can skip the key entirely. Register an OIDC trust, and the workload calls with the short-lived token its own identity provider issues:

pithy dashboard connect --oidc-issuer <url> --oidc-claim <name=value> --kind <agent|script> --purpose "<what it does>"

No keypair and no dashboard, and the same signed-in session names who sanctioned it. At least one claim has to name the workload, because the issuer signs for everybody. Each call then presents the token on pithy-control-plane-oidc, names the trust on pithy-control-plane-trust, and names the one scope it exercises on pithy-control-plane-scope — there is no token to mint, so the per-call table below is the key path’s, not this one’s. connect --oidc-issuer has the claims each known issuer takes, and what a refused call records.

The contract is a module you can import

@pithy-sh/cli/src/dashboard/contract carries the six calls, the six response shapes, and the hosted origin.

It reaches for no timer, no fetch, and nothing from node — so it compiles in a Worker as readily as in a build script.

Implement the client interface against it and let the compiler tell you what you owe, rather than copying the field sets into a test that can drift.

What your client has to do per call

Mint a token that is — and every check your Worker runs on it is worth reading beside this list:

SignedEd25519, alg exactly EdDSA
Audience-boundThe connection id, and this Worker’s environment
Issuer-boundThe issuer the connection was registered against
Short-livedWithin the configured maximum. Sixty seconds is the shape
Single-scopeThe one scope this call needs, never the whole grant
Single-useA fresh token id each time. It is spent on arrival
Body-boundCarrying the SHA-256 digest of the raw body

The body digest is not optional ceremony. A signature over claims that do not bind the body would let an attacker swap the payload under a valid signature.

Discover, do not configure

Compose your navigation and your calls from GET /control-plane/manifest.

Knowing a capability is installed is not enough to call it. Every capability’s mount point is configurable, and each builds its declaration from its resolved config — so the manifest names where things actually are. A client that hardcoded /payments would 404 against exactly the adopters who customized anything.

Each declared route names the scope it needs. Held against the granted scopes, that is what lets you gray out an action that is not granted here instead of offering a button that answers 403.

Map your own roles onto kinds, not onto scopes. Each scoped route also names its scope’s kind — reads, writes, sends, charges, deletes or credentials — declared by the capability that owns the scope. Scopes are open, so a role written as a list of them misses the next one a capability adds; a role written as “may grant reads and writes” caps it by what it does. Read a scoped route with no kind, from a Worker older than kinds, as credentials. Every scope declares its kind has the rules.

A POST can be a read. A route whose input must not be in a URL — a lookup by an address, a search by a term, an export with its reason — is a POST that carries readInBody: true beside kind: "reads". Judge whether a route only reads by the method, the kind and that field together, never by the field alone. A Worker older than the field sends none, and its POSTs are writes.

When one of your people leaves, find what they authorized. POST /control-plane/connections/lookup with { "principal": "<email>" }, under connections:read, lists the connections that email registered on this environment, and POST /control-plane/connections/:connectionId/revoke, under connections:revoke, ends one, with a reason. It refuses your own connection. Send the address in the body, never the URL: a query string is written to every request log on the way to your Worker, so GET /control-plane/connections refuses ?principal= with a 400. The reference has the shapes; from a terminal it is pithy dashboard connections.

Each route also names itself and what it takes. operation is its permanent name within its capability, and input is the JSON Schema of its path, query and body, generated from the validators the route runs — the reference has both. An AI agent needs no client of its own: pithy mcp serves these routes to it as tools, named and typed from exactly these fields.

A capability with no management surface reports an empty list rather than being absent. Composed, but nothing to administer and not installed are different facts, and a client that cannot tell them apart renders the wrong thing for both.

The declaration is checked, not trusted. A hand-maintained list beside generated behavior is a list that rots, and a drifted manifest is worse than none — a client believes it, calls a path nothing serves, and the adopter sees a management client broken for reasons inside somebody else’s package. Every declared route is compared against the router that actually mounted, in both directions, by each capability’s own contract test.

Do not model a scope you do not need

Ping requires a verified caller and no scope at all. It has to work for a connection granted nothing, because it is how a new key is proven before the old one is expired.

ESC