pithy.config.ts

There are two of these files, and the split between them is a decision rather than an accident.

FileHolds
The root pithy.config.tsProject identity and policy — only what cannot be per Worker
apps/<name>/pithy.config.tsWhat that Worker is made of

Together with wrangler.jsonc and a four-line mount file, that is the entire surface you own.

Why capabilities are per Worker

Project structure is where these files sit, the configuration schema is every field, and the Worker contract is what the config assembles.

Everything a capability drives is per Worker: the composed route tree, the bindings written into that Worker’s wrangler.jsonc, and Durable Object class migrations — which register a class against a specific script.

So a Worker declares what it is made of, and a KV-only Worker never sees a D1 it does not use.

The root config

Each key is there because it cannot be per Worker.

const config = {
  name: "acme",
  // environments: ["staging", "prod"],
  // cloudflare: { accountName: "acme", accountId: "" },
  // tokens: { overrides: {} },
  // seed: { productionEnvironments: ["live"] },
  // privacy: { classes: ["pii"] },
  // administersItself: true,
};

name is the leading segment of every Cloudflare name this project provisions, and the only key teardown can find them by. It stops at 26 characters and is effectively permanent — Naming conventions covers why.

environments is every environment this project deploys to, in the order provisioning walks them — least-production first, so a mistake is made in staging before it is made in production. Absent means staging and prod. dev is never listed: it is local, it is the top-level wrangler stanza rather than an env.dev, and it always exists.

It is the one answer to what environments does this project have, and everything that iterates environments reads it. Like name, renaming one does not rename anything provisioned under the old name — it orphans it.

cloudflare says which account this project belongs to, and it earns its keep the moment more than one person deploys.

accountName selects the credentials file. Without it, every project on the machine reads the same one — so a developer working across two companies switches accounts by editing that file in place, every project silently follows, and the next deploy authenticates successfully against the wrong tenant with nothing anywhere disagreeing.

accountId pins the account those credentials must belong to. Every command that resolves them compares the two and refuses on a mismatch, naming both. The nickname means whatever each machine says it means; this is what makes the repository the authority. An account id is an identifier rather than a secret — wrangler configs commit them — so it is safe here, including in a public repository.

seed.productionEnvironments names every environment this project treats as production beyond the built-in ones. Each then requires the type-to-confirm phrase rather than just a flag — a safety rule no single Worker should be able to quietly omit.

privacy.classes declares the privacy classes this project handles: secret, pii, phi, pci, or one you registered with definePrivacyClass. Declaring a class closes console, so pithy deploy refuses while Biome’s suspicious/noConsole or Oxlint’s no-console is off, and the control plane reports what you declared beside what the code holds. It is root for the reason seed.productionEnvironments is: a project’s compliance posture is not something one Worker gets to have and another does not. pithy privacy enable writes it, and a misspelled key is refused rather than read as nothing declared.

administersItself says one of this project’s own Workers is the control plane it calls. A Worker cannot fetch its own hostname: the subrequest loops back through the edge into the Worker it came from and hangs until Cloudflare answers 522, on a route that answers in a second and a half from outside. So with this declared, pithy provision writes one more services entry into every stanza it generates — SELF, pointing at the script that stanza deploys as — and the code calls itself with env.SELF.fetch(request), dispatched inside the runtime with no edge hop. The top-level stanza gets none, and that is the rule rather than an omission: the 522 is an edge behavior, and wrangler dev serves a Worker fetching its own address as an ordinary local request. It is the kit’s job rather than a line you add yourself because a feature environment’s stanza is regenerated on every provision, so a hand-written entry would never survive to the deploy.

The Worker config

const config = {
  domains: DOMAINS,
  capabilities: [
    // pithy:capabilities (managed region — do not remove this marker)
  ],
  app,
};

capabilities is the managed region. pithy add writes into it, in dependency order, and the marker is how it finds the region again. Editing what is inside it is fine; deleting the marker means the next add cannot place anything.

app is your own capability — routes, middleware, tables, bindings, English. It composes last, after every library capability. What is a capability? is the model.

vars declares the plain wrangler vars this Worker reads — a tunable, a feed address, a threshold — built with defineVars: each with a one-line description, a schema, a default, and a value per environment where one differs. pithy worker sync writes them into every stanza of wrangler.jsonc, and the Worker reads them back typed. It is optional, and Environment variables shows it end to end.

domains is where this Worker answers, per environment. It is worth its own section.

The origin is declared once, and derived everywhere

const DOMAINS = {
  staging: { pattern: "staging.api.example.com", zone: "example.com" },
  prod: { pattern: "api.example.com", zone: "example.com" },
};

export const PUBLIC_ORIGIN = originFor(compositionEnvironment(), DOMAINS);

const config = { domains: DOMAINS, capabilities: [ … ], app };

Every capability that needs a public origin asks the same question. Auth builds OAuth callbacks, magic-link URLs and the CSRF allowed-origin from one. Email builds tracking and unsubscribe links. Payments’ return URLs decide where a browser lands after checkout.

Write a URL into any one of them and you have written one environment’s origin into all of them. Three of them, one mistake, three separate discoveries: staging mails real users links into production, an unsubscribe from a staging test unsubscribes them in production, and a staging payer lands in production on an account that bought nothing.

So it is derived. originFor is the one answer to where is this Worker reachable, and it is the same call the CLI makes to generate the BASE_URL var — so the Worker’s runtime origin and the origins its capabilities were configured with cannot disagree.

The CLI evaluates the config for the environment a command is about. pithy migrate, pithy upgrade, pithy provision and pithy deploy’s pending count each take an environment, and while they compose a Worker compositionEnvironment() answers it; pithy dev answers dev. A command that spans every environment — pithy doctor, pithy secrets, a capability’s own provision — reads the config once, where it answers undefined, and pithy doctor’s secret and migration checks compose dev and each declared environment in turn, so each environment’s line is that environment’s own answer.

The declaration is hoisted because the origin has to exist before the capabilities that take it are constructed, and domains: DOMAINS beside them is the same object: one declaration, two readers.

pithy add writes PUBLIC_ORIGIN unquoted for every option whose manifest says its value is an origin. A --set override still wins, because a Worker fronted by something Pithy does not know about has an origin no derivation can produce.

An environment domains does not name resolves to localhost, never to another environment’s origin. An undeclared environment is an unpublished one, so the fallback fails closed: a link that goes nowhere is useless rather than harmful. A deployed environment cannot keep it — pithy deploy --env <name> refuses one that declares no origin.

Name the constant for the Worker rather than for the capability that asked first. The first project to write this called it AUTH_BASE_URL, and that is part of why email and payments kept their hardcoded URLs for days.

One origin deliberately does not derive: the control-plane issuer. It is an identity rather than an address, and a per-environment issuer would make a connection minted in staging unverifiable in production.

Declaring a binding on your own app

Your app is a capability like any other, so it declares the Cloudflare bindings it needs the same way: in requiredBindings. createBackend refuses to boot without them, and pithy doctor names any stanza that lacks one, with the command that writes it. pithy worker sync writes every D1, KV, R2 and queue binding into every stanza of wrangler.jsonc, and pithy upgrade writes every kind, those included, through the same writer.

const app = defineCapability({
  name: "board",
  requiredBindings: [
    { type: "hyperdrive", name: "HYPERDRIVE", target: "a76a99bc342644deb02c38d66082262a" },
    { type: "queue", name: "JOBS" },
    { type: "browser", name: "BROWSER" },
  ],
});

Pithy creates what it owns and carries what you own. A d1, kv, r2 or queue binding gets its resource from pithy provision, per environment and per feature, named <project>-<env>-<thing> and honoring scope: "global" and resource exactly as a capability’s do (the naming rules). A binding the Worker lists in ownBindings in its pithy.worker.jsonc gets the Worker’s own resource instead, <project>-<env>-<worker>---<thing>. A queue is reaped by pithy feature destroy with the rest. Only its producer is written; a consumer is yours.

The other kinds name something you stand up yourself, once, at the account: hyperdrive, browser, images, analytics_engine_datasets, pipelines, mtls_certificates, dispatch_namespaces, ai, ratelimit and email. target is the resource the entry addresses — the Hyperdrive config id, the certificate id, the stream, the dispatch namespace, or the dataset — and it is required wherever wrangler requires it.

A declared target is one id, so every environment gets that id. To point production at its own Hyperdrive config, give env.prod its own entry, and Pithy leaves it alone. A stanza Pithy creates is seeded from the top level, which is dev, and most of these kinds name the same resource everywhere. Three do not: email, hyperdrive and pipelines. A send_email entry is where mail goes, a Hyperdrive config is one database’s connection, and a stream feeds one sink. A feature inherits dev’s. A declared environment starts with none of them, so an entry written for dev is never copied into production. A binding you declare is still written there, with its declared target, which is why production’s own config goes in env.prod.

Deleting the declaration is how you decline one of your own bindings. declinedBindings is about what a capability declares.

A wrangler key Pithy does not model is yours to write by hand. Put it in wrangler.jsonc at the top level. Most such keys, like placement or limits, are inherited by every environment, so once is enough. The rest are keys wrangler does not inherit, such as tail_consumers, containers or vpc_services. Repeat each of those in every env.<name> stanza; pithy doctor reports a stanza that does not. A stanza Pithy creates copies a flat value whole and starts a list empty, so a feature loses those lists. Repeat them under env.feature if your features need them.

Declining an optional binding

A capability marks a binding optional when its own code has a path for the binding’s absence. Usually you never think about it: a capability declares one only when its config asks for the feature behind it.

Sometimes the feature is on and the resource is deliberately not there. Name the binding, with the reason:

declinedBindings: {
  SUPPORT_BUCKET: "no R2 in this account yet; the inbox runs without stored bytes",
},

pithy upgrade then leaves it out, and pithy doctor reports it as declined rather than missing — so a stanza you delete by hand stays deleted instead of coming back on the next upgrade.

pithy provision honors the same declaration: it creates no Cloudflare resource for a declined binding and writes no entry for it, and it prints what it left out, with your reason. Both halves matter, because stopping the upgrade writing the binding while still creating the bucket hands you exactly the resource you declined. It says so in the run rather than only in pithy doctor, because removed work leaves no other trace.

The reason is required, and it is the point. A binding simply absent is indistinguishable from one somebody forgot, which is the state this replaced. Doctor prints your sentence back on every run, so write it for whoever reads the report next.

Reach for the capability’s own config first: turning attachments off is a better answer than declining the bucket, because the capability then declares nothing at all.

Three declines are refused outright — a required binding, a Workflow, and a Durable Object. Optional is the capability’s statement that its code has a path for the absence; a required binding has none. On a Workflow, optional means not provisioned yet, so declining only hides the instruction. And a Durable Object’s class migration tag is written once and never revisited, so a decline arriving after an upgrade cannot undo what that upgrade stamped.

A decline naming a binding nothing composes is reported and never fatal: pithy remove <capability> leaves exactly that state, and a failure no command could clear would be worse than the line that names it. Declining also never deletes a binding an earlier upgrade wrote, and never deletes the resource behind it — which is why pithy provision says Not created by this run rather than a larger claim. pithy doctor names the environments the binding survives in, and removing them is your call.

Pinning a generated value

Some binding entries carry a value Pithy generates for you. A rate limiter’s namespace_id is the one that exists today: it is derived from the binding name, so two limiters can never end up sharing one budget.

That entry is written once, when the capability is composed, and no command revisits it. So when the kit changes how a value is derived, a project that already has the old one keeps it — and keeps it silently, because the config is valid and every check passes. pithy doctor reports the difference, and states both numbers:

    bindings     AUTH_RATE_LIMITER (ratelimit) namespace_id is 1001, and the kit writes 3093 today
                 env: dev, staging, prod. Yours may be deliberate, so nothing rewrites it.
                 Change it, or name it in pinnedBindings to settle the line.

Nothing rewrites it, and that is the design. A namespace_id is a live budget’s identity — two bindings on one id share one counter — so changing it re-partitions traffic that is already flowing. And a value you tuned looks exactly like one that merely predates a change. Only you know which yours is.

Two edits settle the line, and either is correct. Change the value in wrangler.jsonc to what the kit writes, or keep yours and say so:

const config = {
  domains: DOMAINS,
  capabilities: [ … ],
  pinnedBindings: {
    AUTH_RATE_LIMITER: "20/60 is our upstream quota; this id is the budget we've been running",
  },
  app,
};

The reason is required here for the reason it is required on a decline. A pinned value still prints on every run, with your sentence where the instruction was — so the next person reads a decision rather than a difference. A pin whose value already matches the kit, or which names a binding this Worker does not compose, is reported as stale and never fails anything.

The comparison covers only values the kit owns. A limiter’s limit and period are yours to tune and are never reported; a D1 database_name is held to the name pithy provision composes for that Worker by pithy doctor’s Resource names: block, never here; a workflows entry has its own line under Workflows:.

ESC