Add a second Worker

You need: a scaffolded project.

One command

pithy worker is the command, project structure is what it writes into, one project or two is the decision above it, and shared databases is what two Workers with the same binding name get.

pithy worker add admin

It scaffolds apps/admin/ with its wrangler.jsonc (named <project>-admin), its pithy.worker.jsonc, its tsconfig.json and its package.json — then generates every discovered Worker’s .dev.vars, takes a dev port when there is a feature block to take one from, and installs the workspace.

At a terminal it also asks where the Worker answers, per environment, against your account’s real zones, and writes the answer as a domains block.

All-or-nothing. Anything that fails after the directory is made rolls it back, so the same command works on the retry.

apps/ is the registry

There is no hand-maintained list. pithy dev, pithy deploy, pithy migrate and the rest enumerate apps/* and read each Worker’s config.

Add, remove or rename a Worker and the dev set follows automatically.

pithy worker list      what exists, which autostart, which port each holds
pithy worker remove    deletes the directory and releases its port

remove deletes a directory, not a database. Your data is untouched. It refuses while another Worker binds the one going, and names each one to unbind first.

Renaming moves three strings at once

A Worker’s name is three things that have to agree: the directory, the deployed script name, and vars.WORKER — which is what tells two Workers’ audit events apart when they share a database.

pithy worker rename --from admin --to console

Only rename and an interactive add reach Cloudflare, and only to ask a question: rename asks which scripts are live under the old name, and add at a terminal reads your zones for its domain picker. Neither ever writes there. Every other Worker’s binding to it follows the new name; the binding names stay, because that Worker’s code reads them.

sync is the safe one to run any time

pithy worker sync

Writes what the Worker’s config declares into its wrangler.jsonc. It touches no account and runs no deploy — safe on any branch, at any time, as often as you like. Running it twice changes nothing and writes nothing.

Five halves:

The address. A domains block names where the Worker answers per environment, and sync writes the route and the BASE_URL it implies.

This is the only non-interactive way to get that route written. Before it, a domains block added by hand declared an address nothing served — doctor reported it healthy, deploy shipped it, and the Worker answered on nothing.

The Workflows and crons your app capability declares, for every environment.

The D1, KV, R2 and queue bindings the Worker composes, your app’s own requiredBindings and every library capability’s, into every stanza that lacks one — the same entries pithy add and pithy provision write. An entry a stanza already has is left as written.

The service bindings your app declares, in every stanza, at the script each target deploys as there.

The D1 names your ownBindings imply. A binding listed in pithy.worker.jsonc after its entries were written still names the shared database, so sync gives each such entry the name pithy provision composes for this Worker, and the top-level stanza a database_id of its own for local dev. A stanza that already holds a real database_id is left for pithy provision --repoint.

Which Worker composes what

Each Worker has its own pithy.config.ts and composes its own capabilities. An admin Worker that needs no payments does not compose payments.

Two Workers that declare the same binding share one database, unless one lists it in ownBindings — which is why worker is stamped on every audit row, and the only thing that tells their events apart.

One Worker calls another over a binding

A call to another Worker’s hostname goes out through the edge and back. A service binding keeps it inside Cloudflare, and one command declares it:

pithy worker bind --from admin --to api

It writes the binding into admin’s pithy.config.ts and every stanza of its wrangler.jsonc, as API unless you pass --binding. admin then calls env.API.fetch(request). Every environment resolves it to that environment’s copy of api — a feature to its own — and pithy dev sends it to api’s local port. pithy deploy ships api first.

The target can be a kit Worker, named by its capability — --to email — once some Worker composes it. A binding that would close a loop is refused, with the whole path printed. pithy worker unbind takes one out.

The administrative surface goes on one

The control-plane seam is composed on one Worker per project, and a connection targets that one. In a project with several, pithy dashboard connect refuses the ambiguity and asks which.

Before you add one

Read one project, or two? — a second Worker inside one project and a second project are different decisions, and the second is the expensive one to get wrong.

ESC