Configuration schema

The root

pithy.config.ts is the concept page for this file, each entry in capabilities is a capability, every name it composes is held to the naming rules, and what it generates into wrangler.jsonc is bindings.

const config = {
  name: "acme",
  environments: ["staging", "prod"],
  cloudflare: { accountName: "acme", accountId: "" },
};
Key
nameThe project. Capped at 26 characters — see why. A name carrying an f<digits> segment can have no feature environments
environmentsEvery environment this project deploys to. dev can never be declared, and neither can a name whose first segment is f and digits
cloudflareWhich account this project belongs to: accountName selects the credentials file, and accountId pins the account those credentials must belong to
tokensOverrides for a minted token profile’s permissions
seed.productionEnvironmentsEnvironments treated as production beyond the built-in ones
privacy.classesThe privacy classes this project handles. Declaring one closes console: pithy deploy refuses while Biome’s suspicious/noConsole or Oxlint’s no-console is off
administersItselfOne of this project’s own Workers is the control plane it calls, so every generated stanza gets a SELF service binding

A Worker’s own apps/<name>/pithy.config.ts holds what that Worker is made of. Each key is documented on pithy.config.ts.

Key
capabilitiesThe composition, in order. pithy add writes into its managed region
appYour own capability, composed last
domainsWhere this Worker answers, per environment
varsThe plain wrangler vars this Worker reads, built with defineVars: a description, a schema, a default and per-environment values for each. pithy worker sync writes them into every stanza — see declaring your own vars
declinedBindingsAn optional binding this Worker does without, with the reason
pinnedBindingsA generated value this Worker keeps rather than taking the kit’s, also with the reason
retentionHow long this Worker keeps deleted accounts, the audit trail and each class of personal data

environments is load-bearing

Every declared environment is managed, and there is no second, narrower list.

An environment deployed and not managed is an environment whose secrets have no master key — which is a silent failure with a config field making it look intentional.

So declaring an environment is what costs a manager Worker, a D1, a set of resource names. A project that does not want five declares fewer.

domains is what worker sync reads

A domains block names where a Worker answers per environment, and pithy worker sync writes the route and the BASE_URL it implies.

Order matters, and it is yours

Middleware mounts in the order the array lists, and your app capability composes last.

So your middleware runs after auth has resolved the session and before another capability’s own gate — which is exactly what lets you put an authorization rule over somebody else’s route.

Every capability validates its own block

At assembly, not at first use.

An unknown algorithm, a roster a model cannot rate, a board field that is immutable, a plugin id the kit reserves, a category key outside your taxonomy — all fail on deploy rather than at 3am.

Where each capability’s keys live

AuthAuth reference
PaymentsPayments reference
StorageStorage reference
MediaMedia reference
EmailEmail reference
VectorVector reference
SecretsSecrets reference
TurnstileTurnstile reference
i18ni18n reference
AuditAudit reference
SupportSupport reference
TestersTesters reference
LedgerLedger reference
LeaderboardLeaderboard reference
RatingRating reference
MultiplayerMultiplayer reference
MatchmakingMatchmaking reference
Control planeControl plane reference

basePath is on almost all of them

Every capability’s mount point is configurable, defaulting to its own name.

Two consequences worth knowing:

A management client composes its calls from the manifest, which names the resolved path — so a client that hardcoded /payments would 404 against exactly the adopters who customized anything.

Two prefixes are fixed regardless. Email’s tracking callbacks keep /_pithy/email, because a tracking URL is already in somebody’s inbox. And testers’ path is movable but effectively one-shot, for the same reason.

The config is loaded by every CLI command

Which is why a Durable Object class must never be exported from a package entry point — that file is what pithy.config.ts imports, and a cloudflare:workers import on that path takes pithy upgrade down with it.

ESC