Stand up the support inbox: the R2 bucket attachments and raw messages live in, the per-environment classification worker, the full-text index, the semantic message index when search.semantic is on, and, per environment, the Email Routing rule that delivers that environment’s support address to its app worker.
This is the provisioning half of the support capability — provisioning Support has the account steps, and running a support inbox is the day-to-day.
Synopsis
pithy support provision [--worker <name>] [--routing-zone <zone-id>] [--inbound-address <address>] [--app-worker <name>] [--json]
pithy support deprovision --env <environment> [--worker <name>] [--storage] [--routing-zone <zone-id>] [--r2-access-key-id <id>] [--r2-secret-access-key <key>] [--json]Both subcommands reach a Cloudflare account. There is no local mode. provision has no --env flag: it spans every managed environment — staging and prod — in one run. deprovision is the opposite, and requires one: it tears down exactly the environment named. Unlike pithy email and pithy media, no Secrets Store id is needed — the classification worker binds DB and AI and holds no credential to decrypt.
Its Worker deploy is gated. The Worker is deployed carrying a stamp naming the package version and a hash of its resolved configuration, and a run whose stamp matches both ships nothing. Anything the gate cannot establish — no Worker, no stamp, an unreachable account — deploys. pithy deploy --env <env> ships the same Worker without provisioning anything else, and pithy deploy --env <env> --kit --force re-uploads it regardless.
Flags
provision
| Flag | Default | Purpose |
|---|---|---|
--worker <name> | the project’s only Worker | The app Worker whose support(...) registration is provisioned, and whose wrangler.jsonc carries the per-environment DB binding. Required when a project has several |
--routing-zone <zone-id> | derived | Override. The Zone ID of the zone that contains the address’s domain: for help.example.com, the parent zone example.com, where Email Routing for the subdomain is set up. Email Routing must already be enabled for the domain |
--inbound-address <address> | derived | Override. The exact recipient address the rule matches, e.g. support@help.example.com. It must also be listed in support()'s inboundAddresses, which is what claims it |
--app-worker <name> | derived | Override. Deployed name of the app worker running createEntrypoint with the support capability composed |
--json | false | Machine-readable output |
deprovision
| Flag | Default | Purpose |
|---|---|---|
--env <environment> | none — required | The one environment to tear down, declared in pithy.config.ts. With none, or one not declared, it refuses and lists the environments it could act on |
--worker <name> | — | The app Worker whose wrangler.jsonc names the database the audit trail is written to |
--storage | false | Irreversible. Also delete the R2 bucket with every attachment and raw message in it — this is your support history. Only the last environment’s teardown may |
--routing-zone <zone-id> | — | Also remove the project-global rule the three provision flags created, from this zone. Without it that rule is left in place. Only the last environment’s teardown may. The environment’s own rule is removed either way |
--r2-access-key-id <id> | R2_CREDENTIALS | Required with --storage |
--r2-secret-access-key <key> | R2_CREDENTIALS | The secret half of the pair |
--json | false | Machine-readable output |
Routing
With no routing flag, each environment’s address is routed by itself. For every ready environment, provision composes that environment’s pithy.config.ts, which may read compositionEnvironment(), so the address can differ per environment, and reads support’s inboundAddresses. For each address:
- The zone is the active zone on the account whose name is the longest suffix of the address’s domain.
support@help.example.comlives inexample.com’s zone: Email Routing for a subdomain is set up on its parent zone, so a subdomain is usually not a zone of its own. An address whose domain no zone the token can list holds is refused, naming the domain: the account may not hold it, or the token may not be granted Zone Read on it. - Email Routing must be enabled for the domain. The zone’s own Email Routing settings must say it is enabled, for the apex and a subdomain alike, and a subdomain must also pass the zone’s DNS check for it with no missing record. It is never enabled here. Enabling it moves the domain’s MX, and that stays your act. Off, the environment is refused, naming the domain and where to turn it on, and no rule is made.
- The Worker is the one
pithy deploynames for the environment:<project>-<env>-<worker>aspithy initwrites it. - The rule matches the exact address and sends it to that Worker. When every enabled rule claiming the address already sends it there, nothing changes, whatever they are named. The sole enabled rule for the address is updated to send it to the Worker, keeping its name. Several enabled rules claiming it, any of them sending it elsewhere, refuse the environment by name, and nothing changes. A disabled rule is never re-enabled; with no enabled claim,
<project>-<env>-support-inboundis created.
The permissions it takes. Every call routing makes is zone-level: Zone Read to find the zone, Zone Settings Read for the Email Routing settings and DNS check, and Email Routing Rules Write for the rule, each on the zone holding the address. pithy token mint ci-system grants the three on exactly those zones, and a signed-in session asks for them. A token Cloudflare refuses any of them is a refusal for that environment, naming the three. See Cloudflare tokens.
Only on an account the project claims. A rule is made, updated or removed only when pithy.config.ts names the account (cloudflare.accountId or cloudflare.accountName). On an account only the environment names, provision refuses every derived route, saying why, and deprovision refuses before anything is deleted.
A refusal is reported and the run goes on: every other environment is still routed, and the run still exits 0 when one was provisioned. An environment whose composition claims no address is skipped. An address two environments both claim is refused for both, because one exact-address rule sends it to one Worker: give each environment its own address, or use the flags.
The three routing flags are an override, and all or nothing. Pass all three and they replace the derivation with exactly the rule they describe: one project-global rule named <project>-global-support-inbound, on the zone named. They are held to the same checks a derived route is: an account the project claims, a zone the token can list, and Email Routing enabled for the address’s domain. Pass one or two and the run is refused before anything is created. Enabling Email Routing points the domain’s MX at Cloudflare, so use a subdomain, never your apex.
What it does
provision, in order — and the order is the inverse of how it fails:
- Preflight. Verify the account can host a Workflow at all.
- Bucket. Create or reuse
<project>-global-support. One bucket for the project rather than one per environment: theSUPPORT_BUCKETbinding hangs off the app worker that receives the mail, and every declared environment’s stanza points at that one name —pithy provision --env <name>writes thebucket_name, composing it from the same declaration this command does. When the capability is configured with attachments off and no raw retention, no bucket is created and the step reportsskipped. - Message index. With
search.semanticon, create<project>-<env>-support-messagesin Vectorize for every managed environment, before the worker that binds it is deployed: a deploy that binds an index nobody created fails. 1024 components andcosinefor the default@cf/baai/bge-m3; a{ model, dimensions }of your own sets the width. An index that exists is reused, and one that exists at another shape is refused rather than queried in the wrong space. With it off, nothing happens here. See Search. - Workers. Deploy the prebuilt classification worker for every managed environment. It reads a message and writes a label over the
AIbinding, and withsearch.semanticon it embeds the message into the index too. It also hosts the reprocess Workflowpithy vector reprocess --index support-messagesstarts. - Search index. Create or drop the full-text index and its three triggers in each environment’s app database to match
search.fts, which is on by default. A provisioning step rather than a migration, because the index is derived — every row in it comes frompithy_support_messages— and because aCREATE TRIGGERcomposed conditionally on a config flag is what the migrator reads as ledger corruption. A newly created index is backfilled immediately, so the inbox never answers no matches for a term plainly in a body. The triggers — anAFTER INSERT, anAFTER UPDATEand anAFTER DELETEonpithy_support_messages— are what keep the index in step, so a message is indexed because it was written rather than because the code that wrote it remembered. Re-run this after every upgrade of@pithy-sh/support. Until it has run, search is theLIKEfallback. A database whose table is there and whose triggers are not is repaired and backfilled here, and reported assearch index triggers restored and backfilled;pithy doctor’sSupport search:block names any environment still in either state.pithy backupleaves the index out, andpithy restorerebuilds it with this same step. - Message index, settled. An index that holds nothing yet is backfilled once: one step 3 created, or one that exists while inbound mail does and no message carries a stamp — what a run that failed after creating the index leaves, so re-running provision finishes the job. The run starts the reprocess Workflow over every inbound message and does not wait for it. An index holding any stamp is never re-embedded here; that is
pithy vector reprocess. Withsearch.semanticoff, an index that exists is dropped, after the deploy that stopped binding it, with the model stamps inpithy_support_embeddingsthat named its vectors. Looking for it is the only Vectorize call a run with semantic search off makes, and a token without a Vectorize grant, or an account without the paid Workers plan Vectorize needs, answers it with nothing to drop rather than failing the run. Either way the app Worker’swrangler.jsoncfollows: theSUPPORT_VECTORIZEentry is written into each environment’s stanza while the index exists, and taken out when it is dropped, because a binding to a deleted index fails the next deploy. - Routing rules. Last, and only when at least one classification host went up: each ready environment’s own, or the one the flags name. See Routing. Creating a rule first would start delivering mail to a Worker whose classification host is not deployed yet — a window in which real customer messages arrive and stay uncategorized with nothing to say why.
Each environment’s deploy needs the app DB id from that environment’s stanza. A missing stanza or id is refused rather than deploying a worker that would write its classifications into nothing.
A Worker that owns what the host binds gets its own. When --worker names a Worker that lists a binding the support host binds in its ownBindings, provision deploys that Worker’s own host, <project>-<env>-<worker>---support, bound to the Worker’s own resources, and writes its Workflow bindings to reach it, <project>-<env>-<worker>---support-<job>. The shared <project>-<env>-support is left alone. With search.semantic on, that host fills an index of the Worker’s own, <project>-<env>-<worker>---support-messages, since its vectors are keyed to the Worker’s own rows, and the backfill runs through the Worker’s own <project>-<env>-<worker>---support-reprocess. See a Worker’s own kit hosts.
deprovision removes the environment’s own routing rule first, so mail stops before its handler does: each rule that sends one of the addresses its composition claims to its app Worker. A rule for the address that sends it anywhere else is left, and so is every other environment’s. The project-global rule the provision flags created goes only with --routing-zone, and only with the last environment. Then it removes the named environment’s <project>-<env>-support-classify and <project>-<env>-support-reprocess Workflows, then its classification worker, and every Worker’s own support host and its Workflows, found by recomputing their names. The Workflows go before the workers, because deleting a Worker leaves the Workflows registered against it. The bucket stays unless --storage is passed, and with it the key pair is resolved before the worker comes down.
--json
support provision
| Key | Type | Meaning |
|---|---|---|
command | "support provision" | The subcommand that produced this line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
bucket | object | The R2 bucket, and what happened to it |
bucket.bucket | string | The bucket name. Reported even when the step was skipped, so the name is always readable |
bucket.created | boolean | True only when this run created it |
bucket.skipped | boolean | True when attachments are off and raw retention is off, so no bucket was wanted |
environments | string[] | The environments a classification worker was deployed for |
skippedEnvironments | array | One entry per environment nothing was provisioned for, with its env, its reason, and the action that resolves it. For production that action says the run is a person’s decision rather than naming a fix |
search | array | What the full-text index did, per environment |
search[].env | string | The environment this entry describes |
search[].created | boolean | The index was created and backfilled in this run |
search[].dropped | boolean | The index was dropped in this run. Both false means it already matched the config |
search[].repaired | boolean | Its triggers were missing and were restored, and the gap backfilled |
semantic | array | What the semantic message index did, per environment. Absent from a @pithy-sh/support that predates it |
semantic[].env | string | The environment this entry describes |
semantic[].indexName | string | The environment’s index, <project>-<env>-support-messages, or <project>-<env>-<worker>---support-messages for a Worker’s own host |
semantic[].created | boolean | The index was created in this run |
semantic[].dropped | boolean | The index was dropped in this run, because search.semantic is off |
semantic[].backfilled | boolean | This run started the index’s one backfill: for an index it created, or one that holds no stamp while inbound mail exists |
routing | object | The inbound Email Routing rules, in sum. inboundRoutes has each one |
routing.created | boolean | True when this run created or updated a rule |
routing.skipped | boolean | True when there was nothing to route: every environment claims no address |
inboundRoutes | array | Each inbound rule this run settled: one per address per provisioned environment, or the one the three routing flags name |
inboundRoutes[].env | string or null | The environment the rule routes, or null for the project-global rule the flags name |
inboundRoutes[].address | string or null | The exact address the rule matches. null when the environment’s composition claims none |
inboundRoutes[].zone | string or null | The zone the rule lives on, by name: the zone holding the address’s domain, the parent zone for a subdomain. null when no zone the token can list holds it |
inboundRoutes[].zoneId | string or null | That zone’s id. null when no zone holds the address’s domain |
inboundRoutes[].worker | string or null | The app Worker the rule sends the mail to, as pithy deploy names it for the environment. null when it could not be resolved |
inboundRoutes[].outcome | "created", "updated", "unchanged", "skipped" or "refused" | created: this run made the rule. updated: the sole enabled rule for the address sent it elsewhere, and now sends it to the Worker. unchanged: a rule already did. skipped: the environment claims no address. refused: no rule was made |
inboundRoutes[].reason | string or null | Why the route was skipped or refused, naming the domain. null otherwise |
exitCode | integer | The status the run exits with: 0. A run that provisions nothing writes no report |
One outcome, never two. A run that went ahead writes this report alone and exits 0, whether or not some environments were skipped — exitCode says so, and it matches $?. A run in which every environment was skipped provisioned no environment, so it writes nothing on stdout: the {"error":…} line on stderr is the whole answer, exit 3, with the provisioning command as its fix, and its message names the bucket when this run created it.
$ pithy support provision --worker api --json
{"error":{"code":"core/precondition_failed","status":412,"message":"No environment is ready — staging and prod have no DB database_id. It created the project's support bucket (acme-global-support), which every environment shares.","action":"Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy support provision --json --worker api` again.","exit":3,"retryable":false,"fix":"pithy provision --env staging --yes"}}
$ echo $?
3That line is on stderr, and stdout is empty.
support deprovision
| Key | Type | Meaning |
|---|---|---|
command | "support deprovision" | The subcommand that produced this line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
env | string | The one environment torn down — the value of --env |
storageDeleted | boolean | Whether --storage was passed |
routingZone | string or null | The zone id the project-global rule was removed from, or null when --routing-zone was not passed and that rule was left in place |
inboundRoutes | array | This environment’s own inbound rules: one per address its composition claims |
inboundRoutes[].env | string | The environment torn down |
inboundRoutes[].address | string or null | The address the rule matched. null when the composition claims none |
inboundRoutes[].zone | string or null | The zone the rule lived on, by name. null when no zone holds the domain |
inboundRoutes[].worker | string or null | The app Worker the rule sent mail to. null when it could not be resolved |
inboundRoutes[].outcome | "removed", "absent" or "skipped" | removed: this run deleted the environment’s rule for the address. absent: no rule sent it to the Worker. skipped: nothing could be looked up |
inboundRoutes[].reason | string or null | Why the removal was skipped. null otherwise |
Search
The inbox is searched at POST {basePath}/threads/search, behind support:threads:read, with the words, the mode, the limit and the inbox list’s filters in a JSON body: the words are often a customer’s address or order number, and a query string is written to every request log. Search is its own route, not a filter on the list: a query goes in, ranked threads come out, up to a limit, with no cursor. The inbox list, GET {basePath}/threads, no longer takes q, and refuses it as validation/invalid_input rather than ignoring it.
| Field | Type | Default | Meaning |
|---|---|---|---|
q | string | — | What to search for, up to 200 characters. Required |
mode | string | every backend that is on | keyword, semantic or hybrid. semantic or hybrid with search.semantic off is a 400 naming the flag |
limit | integer | 20 | Threads to return, at most 50 |
archived | boolean | false | true for the done pile |
category, declaredCategory, priority, sentiment, channel, inbox, assignee | string | — | The inbox list’s filters, applied in D1 after retrieval |
The body is strict: an unknown field, cursor included, is a 400.
Keyword finds the exact words: FTS5, on by default, ranked by bm25; the LIKE scan with search.fts off or the index not yet provisioned, which has no score and ranks by recency. Semantic finds the meaning: the query is embedded with the index’s pinned model and Vectorize returns the 100 nearest message ids, with no payload. Hybrid, the default, runs both and fuses them by reciprocal rank fusion over rank position, so a thread both found rises above one only one found. A tie goes to the keyword hit, then to lastMessageAt, newest first — which is what keeps an order number first: semantic search cannot retrieve it, so its thread is keyword’s first while semantic’s first is some other thread, and the two tie.
A thread is scored by its best-matching message and appears once. Each result names that message, messageId, and carries its raw bm25 and similarity, each absent when its backend did not run or did not match it — never normalized into one number. backends.ran names what answered, and backends.skipped names what was on and could not: FTS5 configured and not provisioned falls back to the LIKE scan, and a message index not yet bound, or a model that does not answer, is skipped. A skip degrades the search; it never fails it. Filters run after retrieval, so a narrow one can return fewer than the limit, and count is the true number.
Semantic search costs a second inference per inbound message, on your Workers AI binding, on top of classification — roughly double the capability’s per-message AI cost, and the volume guard bounds messages, not spend. That is why search.semantic is off until you turn it on. The embedding runs in the classification Workflow, after the message is stored and, with ai.enabled on, classified. With search.semantic on and ai.enabled off, the Workflow still starts for each inbound message as it arrives, so an inbox that does not classify is still searchable by meaning. Auto-submitted mail starts no Workflow on arrival, so it is neither classified nor embedded then; provision’s one-time backfill and every pithy vector reprocess --index support-messages embed every inbound message, auto-submitted mail included. An embedding that fails on arrival is not fatal: the message stays out of semantic results until pithy vector reprocess --index support-messages picks it up. Vectors carry message ids and nothing else; the text stays in D1.
Errors
Incomplete routing flags.
The inbound routing options are incomplete.
Pass --routing-zone, --inbound-address, and --app-worker together, or none of them.The capability is not configured. No Worker’s pithy.config.ts composes support. Exit 3 (core/precondition_failed). The project’s only Worker, unnamed, gets pithy add support --worker <worker> --with-prerequisites as its fix, <worker> being its apps/ directory, and --with-prerequisites only when that Worker does not compose secrets yet. Under --json every refusal here is one {"error": …} line on stderr with exit, retryable and, where the cause is known, fix, and the process exits by its class.
The capability will not load. Distinct from the above, and classified rather than assumed — not installed, could not be loaded, installed and will not load, or installed but incomplete. Only could not be loaded, a dependency of the package not installed, is told to install the project’s dependencies. An import that names something no install provides, or a path the installed package does not have, gets no install remedy, and the action names the package that wrote the import.
Credentials are missing.
The project has no name. The bucket is found by name and reused, so a guessed name would adopt another project’s inbox.
No environment is ready. Every declared environment was skipped, so no environment was provisioned: exit 3, core/precondition_failed. The action names the provision each skipped environment needs. Its fix is pithy provision --env <env> --yes when exactly one of them is an environment an agent may provision; a production one is a person’s decision. The bucket is created however many environments skip, and when this run created it, the refusal says so, by name. A bucket an earlier run made is reused and not mentioned.
The app Worker’s environment is not wired.
Half an R2 key pair with --storage, or none at all. Both refused before a worker comes down.
Several Workers and no --worker. The same input/required refusal pithy add raises, exit 2.
Examples
Provision, with Email Routing enabled for help.example.com:
$ pithy support provision
Bucket acme-global-support ready.
staging classification worker deployed, search index created
prod classification worker deployed, search index created
staging: staging@help.example.com now routes to acme-staging-api, on example.com.
prod: support@help.example.com now routes to acme-prod-api, on example.com.
Done.Run it again and each line says already routes to. A domain Email Routing is not enabled for is refused, and everything else still provisions:
prod: No routing rule. Email Routing is not enabled for help.example.com. Turn it on for the subdomain in the Cloudflare dashboard under example.com > Email > Email Routing > Settings > Subdomains, and the next run routes it.The override, machine-readable:
pithy support provision --routing-zone 0a1b2c3d --inbound-address support@help.example.com --app-worker acme-prod-api --jsonTake staging’s worker and its rule down, and keep the history:
$ pithy support deprovision --env staging
staging: classification worker removed.
staging: staging@help.example.com no longer routes to acme-staging-api.
Done.