Five minutes, an empty directory, and no Cloudflare account. At the end of it a Worker is answering on localhost, and you will have seen every file you are expected to own.
You need the CLI installed and Node 22.18 or newer. Nothing else.
1. Scaffold
mkdir my-backend
cd my-backend
pithy initIt asks seven things, six on a web-only project, and you can press enter through most of them.
The project name. It defaults to the directory’s name. This one is worth ten seconds of thought, because it leads every Cloudflare resource this project will ever provision — <project>-<env>-<thing> — and renaming it later does not rename them, it orphans them. It stops at 26 characters. One project, or two? is the scope question sitting behind it.
The first Worker’s name. Defaults to api, and it becomes the directory apps/api/. A project has as many Workers as it needs; another app is another Worker, not another project.
Which environments you deploy to. staging and prod is offered as the default, so one keypress is the whole answer. dev is never listed — it is local, it always exists, and it is never deployed.
Which clients call this backend. Mobile apps, a web app, or both. mobile, the default, scaffolds the API alone, which is what this page assumes. web and both also put a React front end in the first Worker, the way pithy ui add react would. The backend is the same either way.
Which linter runs the kit’s lint rules. Biome, the default and what this page assumes, or Oxlint. Either way you get the same safeguards — no console in a Worker, no raw request input, no TypeScript that Node’s type stripping cannot load, and more — as GritQL rules in biome.jsonc or as an Oxlint JS plugin in .oxlintrc.json. Biome formats either way. pithy init has the full list.
Whether to add a React Native app, on mobile or both. The default is no, and this page takes it. A yes writes an Expo app for iOS, Android and the web into apps/app/, beside the Worker it calls; React Native is what comes next.
Your Cloudflare credentials. Press enter to skip. You do not need an account for this page, and when you do, pithy cloudflare connect signs you in through the browser with no token to make by hand; pithy doctor names that sign-in until one is set. If you do paste a token, init discovers which account it can see, and writes the credentials to the config directory outside every checkout — never into your repository.
2. Set it up
pithy setuppithy setup installs first. The scaffold has no lockfile yet, so it installs with the package manager that launched pithy — Bun when pithy runs under it — and that install writes the first one. Commit it. Then it mints the local secrets, migrates dev, pins this checkout’s ports and seeds. It never reaches Cloudflare, and a second run changes nothing.
Cloned a Pithy project instead of making one? The same command makes that checkout ready, and step 3 is the same too.
3. Run it
pithy devThat starts every Worker in apps/, on ports pinned for this checkout, under one supervising process. At a terminal it pins a live roster beneath its output: each Worker, its port, its state and how long it took to come up, with keys to restart one, open it, or show its output. Worker output stays hidden until you ask for it, and a Worker that fails shows its own. Piped, under --json or in CI, it prints a labeled line per Worker and one ready banner instead. The port for a single-Worker project is 8787.
4. Ask it if it is alive
In a second terminal:
curl http://localhost:8787/healthYou get {"status":"ok","version":…} — status is the liveness answer, and version is the deployed build id, which is null when the Worker cannot tell. GET /health is mounted by createEntrypoint and is public on purpose: it reads nothing about the caller, so there is no credential to send it.
That is the whole loop. Stop it with Ctrl + C, which tears down the Worker subtree with it.
What just got written
treeView-beta
my-backend/
pithy.config.ts ## project identity and policy — the name, the environments
package.json ## workspaces: apps/*
AGENTS.md ## how an agent drives this CLI, in a marked Pithy block
CLAUDE.md ## one line: @AGENTS.md
biome.jsonc ## the linter, configured
tsconfig.json ## a solution file
vitest.config.ts
vitest.workers.config.ts ## tests against real D1 and KV, through Miniflare
plugins/ ## the GritQL lint rules
apps/
api/
pithy.config.ts :::highlight ## what THIS Worker is made of
wrangler.jsonc ## wrangler's file — bindings, per environment
pithy.worker.jsonc ## yours — the dev manifest for this Worker
src/
index.ts :::highlight ## the mount file
bindings.workers.test.ts
Two of those files matter more than the rest.
apps/api/src/index.ts is the entire Worker.
import { createEntrypoint } from "@pithy-sh/core/src/createEntrypoint";
import config from "../pithy.config";
export default createEntrypoint(config);createEntrypoint assembles the capabilities named in the config into one Hono app: typed db and kv registries on every request, binding validation that fails fast with the binding’s name, and GET /health. It also fans inbound mail to any capability that handles it, which is how bounce processing works without you wiring anything.
apps/api/pithy.config.ts is what you own. Two lists and an app:
const config = {
domains: DOMAINS,
capabilities: [
// pithy:capabilities (managed region — do not remove this marker)
],
app,
};pithy add <capability> writes into that managed region. app is your own capability — routes, middleware, tables, bindings — and it composes last, after every library capability. There is genuinely nothing else. Handler code for auth, payments or storage never lands in your repository unless you ask for it with --eject.
Two things worth knowing now
Nothing here touched Cloudflare. pithy dev runs the Worker through Miniflare, the same local runtime wrangler dev uses, against local D1 and KV under .wrangler/state. Real resources arrive with pithy provision, and not before.
Ports are assigned, never probed. Each Worker’s port is pinned in this checkout’s .dev.config.json, out of a block reserved for this branch in a registry held once per machine. That is what lets several projects and several worktrees of each run at once. If something external has taken a pinned port, pithy dev reports the conflict and stops rather than quietly moving — a Worker that changes address breaks every sibling that was told where to find it.