Module

Control plane

Let a management client — the Pithy dashboard, an AI agent through pithy mcp, or one you write yourself — reach into your own Worker, with no data plane in between. Present and denying by default: with no connection registered, every route answers 403.

@pithy-sh/core

terminal
pithy add controlplane

What it is for

How a management client — the Pithy dashboard, an AI agent you connect with pithy mcp, or one you write yourself — reaches into your own Worker to read and administer your own data, with no data plane in between.

Capabilities contribute their own admin routes behind it, so adding one adds its management surface with nothing to wire.

Past reading, a management client can act, behind scopes you grant separately from the reads: credit, debit, reverse and release in the ledger, hide, unhide and correct a leaderboard entry, recalculate or reset a rating, cancel a matchmaking invite or drop a player from a queue, close a multiplayer session or void its result, revoke a git token in artifacts, and assign a support thread. It can also see who else has a record open, live, through a presence room that runs in your own Worker.

Pointing an agent at it. pithy mcp connect registers an agent's own connection and writes the entry into your MCP client, and pithy mcp serve offers it your Worker's admin routes as tools, read from the manifest each time it asks. A tool is offered only when your Worker composes the capability and granted the scope, so a call is never offered and then refused. Each tool says what kind of thing it does, in its description and in the MCP annotations a client reads, so a client that asks before a destructive call asks before a charge, a delete or a credential change. Every call is a control-plane call, audited with actor kind agent.

Running it from CI with no key at all. Register an OIDC trust instead, pinned to your repository's id and its environment, and the job presents its own short-lived token on each call, naming the one scope it uses. Nothing secret is stored at either end.

Knowing what a grant can do, and taking back what someone authorized. Every admin scope declares a kind: it reads, writes, sends, charges, deletes, or touches credentials. Every connection records who authorized it, and when that person leaves, pithy dashboard connections --principal lists everything they authorized across your environments and --revoke ends it.

What it sits on

Your D1 and your Worker. It ships inside core, so it is already installed.

Adding it composes it; connecting a client is a deliberate second step.

  • D1
  • Workers

The honest bit

Present and denying by default. There is no backdoor to open.

A Worker that has never been connected answers every control-plane route with a refusal. There are two kinds of credential, and neither is a secret you share. A key is asymmetric: the client holds a private key, you hold and can revoke the public one. An OIDC trust holds no key at all: a CI job presents the token its own provider minted, and your Worker checks it against the issuer and the claims you pinned. So nothing secret of yours ever leaves your infrastructure, and a breach on our side is not a breach on yours.

Rotation is append, prove, then expire, so a failed rotation leaves the old key working. Revocation is a row you change: immediate, and needing nothing from us. A trust's tokens cannot be recalled, only the trust, so a token already minted stays usable for the minutes until it expires, and the command that revokes it says so.

If you build it yourself

Letting something in is the easy half. Getting it back out is not.

Any API can be opened. The design problem is revocation you control.

Credentials that are not shared secrets

A shared secret means their breach is your breach. A public key you hold means a compromise on their side is inert the moment you revoke it, and a CI job proving its own identity needs no key to leak.

Denying by default

An unconnected Worker must refuse, with no flag left off and no backdoor to open.

Rotation that cannot lock you out

Append, prove, then expire — never replace.

One scope per call

A key signs a token for one scope, bound to a digest of the request body, checked for replay, and expiring in a minute. A CI job's identity token proves who, not what, so each call still names its one scope, and the grant is checked every time.

An audit trail of the vendor

What a management client did, recorded separately from what your users did, and marked dashboard, agent or script.

terminal
pithy add controlplane

Composes with

It depends on seams, never on another module's internals.

In the dashboard

Administer it from a browser, without building the screen.

This capability is what the dashboard talks to. Connecting it is what makes every other pane readable.

The dashboard is the admin interface for your own application: whatever this capability writes, your team can look up, check and act on from a browser. Reading is free, forever, with no time limit. Connect the project when you deploy.

Add it, and get on with the feature.

One command installs the package, wires its bindings into every environment your project declares, and runs its migrations.