Every Cloudflare resource Pithy provisions is named by one rule.
<project>-<env>-<thing>Kebab-case, project first, environment second. No namespace is exempt.
Why there is a rule at all
The rules and their limits are the reference, pithy provision is what composes a name against them, and one project or two is the decision that sets the first segment.
Every Cloudflare namespace Pithy writes into is flat and account-wide: D1 databases, KV namespaces, R2 buckets, queues, Vectorize indexes, Worker scripts, Workflows, the Secrets Store, the API-token list. None of them can be partitioned.
So the name is the partition. The project segment is the only thing keeping two Pithy projects in one account from adopting or overwriting each other’s resources — because provisioning finds a resource by name and reuses it, and without a project segment find then create means a second project silently inherits the first’s database.
What each namespace gets
| Namespace | Name | Example |
|---|---|---|
| D1 | <project>-<env>-<binding> | acme-prod-db |
| KV | <project>-<env>-<binding> | acme-prod-sessions |
| R2 | <project>-<env>-<capability> | acme-prod-storage |
| Queue | <project>-<env>-<binding> | acme-prod-jobs |
| Artifacts namespace | <project>-<env> | acme-prod |
| Vectorize | <project>-<env>-<capability>-<index> | acme-prod-vector-docs, acme-prod-support-messages |
| Worker script (capability host) | <project>-<env>-<capability>, or <project>-<env>-<worker>---<capability> for a Worker’s own host | acme-prod-email, acme-prod-billing---email |
| Worker script (your own) | <project>-<env>-<worker> | acme-prod-api |
| Workflow | <project>-<env>-<capability>-<job>, or <project>-<env>-<worker>---<capability>-<job> on a Worker’s own host | acme-prod-email-send, acme-prod-billing---email-send |
| Secrets Store entry | <project>-<env>-<secret> | acme-prod-secrets-encryption-keys |
| API token | <project>-<env>-<profile> | acme-prod-ci-system |
The <thing> segment is the binding name for a resource pithy add proposes into your config, and the capability for a resource that capability’s own provision command creates.
A binding is shared by name, unless a Worker owns it. Two Workers that both declare DB are backed by one D1. A Worker that lists DB in ownBindings in its pithy.worker.jsonc gets its own, with the Worker in the thing segment: <project>-<env>-<worker>---<binding>, so apps/billing owning DB is acme-prod-billing---db. That holds for D1, KV, R2 and queues, and <worker> is the apps/ directory. It holds for the kit hosts that read them too: a Worker that owns a binding a capability’s host binds gets that host to itself, so apps/billing owning DB and composing email has acme-prod-billing---email beside the shared acme-prod-email. Naming rules and limits has the rest: why three hyphens, what a feature names it, which hosts a Worker owns, and what moving a binding between shared and owned does.
Your own Worker’s script name is the one the kit reads rather than composes. wrangler deploy --env staging appends the environment to the top-level name unless the stanza declares one, so pithy init and pithy worker add write the kit’s shape out — <project>-<env>-<worker> — and the read finds it. A project that never declared a name keeps wrangler’s <name>-<env>, unchanged and deliberately so: recomputing it would rename the deployed Worker of every existing adopter, and a Worker script is a name you cannot change without leaving the old one live, serving and billing.
Which is why a Worker may not be called email. Under this shape apps/email deploys as <project>-<env>-email — byte-identical to the host Worker the email capability’s own provision creates. Cloudflare’s script namespace is account-flat, so a deploy replaces it silently and the capability’s Workflows stop running. Every capability that ships a host owns its name, and pithy init --worker, pithy worker add and pithy worker rename refuse it. email-api is fine; the collision is with the exact name, not with a prefix.
Three things deliberately not on that list
Worker binding names — DB, SESSIONS, MEDIA_BUCKET — never carry the project. A binding is a variable name inside your own Worker, and two projects cannot collide on it. Prefixing one would be a breaking change to your code for no benefit.
Secret registry keys never carry it either. For a Secrets Store secret, the registry key is the Worker binding name; only the store entry it resolves to is scoped.
Table names stay pithy_<capability>_<table>. They live inside one database, which is already project-scoped by the database’s own name.
Two stores a name cannot reach
Cloudflare Images and Stream are the exception. An asset in either is keyed by an id Cloudflare mints on upload rather than by a name you choose, so there is nothing to put a project segment into.
Ownership is carried in metadata instead — every asset Pithy creates is stamped with the project and the environment, the same two keys in both stores, so one query answers what does this project own across them. The stamp is merged last, so a caller’s own metadata cannot displace it, and a Worker that cannot name its project refuses to mint rather than writing an asset nobody can attribute.
That is weaker than a name, deliberately: nothing stops two projects’ assets sitting side by side, because ids are unique and neither can adopt the other’s. What the stamp buys is attribution.
Why project first, environment second
Project first, because the project is the ownership boundary and every operation that asks is this mine keys on the leading segment. Teardown recomputes a name rather than scanning for it. Token listing filters on the prefix. A hashed or truncated project segment would break both, which is why the project is never truncated.
Environment second, because these names land in listings nobody can filter — wrangler d1 list, the account dashboard, the Secrets Store. All any of them offer is sort order.
Sorting should group a project’s resources and then that project’s environments, so everything belonging to production sits in one block. Putting the environment last scatters production through the listing, interleaved with staging. That is exactly the moment somebody acts on the wrong one.
prod, not production
The environment sits in the middle of every name and is never truncated, so every character of environment costs a character of project name, one for one.
production is six characters longer than prod — six characters off the project-name cap for every adopter, spent on a word that says nothing prod does not. --env production is answered with an error naming prod.
An environment stops at seven characters, the length of staging. That is a derivation input rather than a preference: every project-name budget is computed against a seven-character environment, and a longer one would retroactively shrink a cap projects have already been accepted under. A provisioned project cannot be renamed, so the cap cannot move.
A custom environment is fine — live, eu-prod — held to the same character set and the same seven. It is read verbatim, never kebab-cased, unlike the project name: a project name is prose typed once, so Acme Corp is politely composed into acme-corp, while an environment is an identifier repeated in a flag, a filename and a wrangler key.
One shape is refused: an environment cannot start the way a feature branch does. A feature takes the same slot with f<issue>, so an environment called f1-demo once stamped <project>-f1-demo-api into its stanza — feature 1-demo’s Worker, character for character — and pithy feature destroy on that branch deleted it. An environment whose first segment is f and digits is refused: f1, f12-ab, f01. Nothing else is: fr-1, f1a and fix are fine, because no name composed under them can be a feature’s. For the same reason, a project name with an f<digits> segment of its own can have no feature environments at all.
global in the environment slot
Some things are shared across every environment on purpose. They put the literal global in the slot rather than omitting it, so the scheme has no exception to remember.
| Resource | Why it is global |
|---|---|
| The email suppression list | Do not email this person again is not an environment-local fact. An address that hard-bounced in production must not be retried from staging, or the sending domain’s reputation pays for the distinction |
| The support inbox’s bucket | A thread does not belong to an environment; environments are separated by which bucket an operator binds |
The bounce rule, and the support rule pithy support provision’s routing flags create | One rule per zone; environments are separated by which Worker it points at. Without the flags, each environment’s support address gets its own rule, <project>-<env>-support-inbound, to its own Worker |
global is a scope decision rather than a shortcut. Anything not on a list like that one is per-environment.
Two of those are Worker bindings, and they say so in code rather than in a list. EMAIL_SUPPRESSIONS and SUPPORT_BUCKET carry scope: "global" in their capability’s pithy.manifest.json, and every writer reads it: pithy add proposes the name, pithy provision creates the resource under it, pithy worker sync refuses to own it, pithy doctor’s Resource names: block holds each stanza to it, and the capability’s own provisioner composes it through the same expression. Before that the manifest had no way to say it, so pithy add email wrote a per-environment suppression database into every stanza while pithy email provision created the one global one — two names for a resource defined as one, and an unsubscribe recorded through either was invisible to the other. pithy doctor’s shared: section reports a project still in that state. The other entries above are not bindings, so the table stays the statement of record for them.
The project name
It comes from name in the root pithy.config.ts, and nothing else. It is never guessed.
A resolver that guesses exists for display, falling back to a Worker’s name and then the directory basename — good enough to print, catastrophic to provision under, because teardown would later compute names matching nothing, delete nothing, and exit 0.
It starts with a letter, holds only lowercase letters, digits and single hyphens, and stops at 26 characters. Charset and length are one rule with one home because they fail the same way. Acme Corp is fine; 2026-launch is not.
The rule is enforced where the name is minted and again every time it is read, so a name that cannot become a Worker script name is refused before anything is provisioned — rather than at the first host deploy, which would leave a project half-built under names it can never finish using.
The caps differ a lot by namespace
Cloudflare’s limits are not one number, and Pithy holds each one separately.
| Namespace | Cap | Over it |
|---|---|---|
| Worker script | 63 | Refused |
| Workflow | 64 | Refused |
| Vectorize index | 64 | Refused |
| R2 bucket | 63 | Truncated |
| Queue | 63 | Truncated |
| KV namespace title | 512 | Truncated |
| D1 database | 128 (Pithy’s) | Truncated |
| Secrets Store entry | 128 (Pithy’s) | Truncated |
| API token | 128 (Pithy’s) | Truncated |
The Worker script cap is 63 rather than Cloudflare’s general 255 once workers.dev is on, which it is by default. Three of those caps are Pithy’s own where Cloudflare documents none — a stated ceiling is better than discovering an undocumented one in production.
Naming rules and limits has the arithmetic, including how much room a 12-character project leaves for the rest of the name, and the feature-branch budget for the tightest shape of all — where nothing is truncated, and a branch slug that does not fit is refused with the maximum that would.