A personal image host that runs entirely on Cloudflare. Originals live in R2, metadata in D1, and a Hono API on Workers manages everything. The pix CLI comes first and a web UI comes later. The design lives in ~/Markdown/cloudflare-image-service-plan.md, which is the source of truth.
| Hostname | Purpose |
|---|---|
pix.stagerightlabs.com |
Public image serving and transformations |
pix-api.stagerightlabs.com |
Management API (bearer tokens) |
Both names are Worker vars (PUBLIC_HOST, API_HOST), not hard-coded.
- Node 22+ and pnpm 12
- A Cloudflare account with Workers, R2 and D1 enabled
pnpm install
pnpm --filter @pix/api types # generate worker-configuration.d.ts (rerun after editing wrangler.jsonc)
pnpm dev # http://localhost:8787/health
pnpm test # Vitest inside the Workers runtime (local R2 and D1)
pnpm typecheck
pnpm lint # Biome; `pnpm format` applies fixesLocal secrets go in apps/api/.dev.vars (git-ignored; copy .dev.vars.example). ADMIN_TOKEN is required.
Drizzle generates SQL migrations and Wrangler applies them to D1:
cd apps/api
pnpm db:generate # after editing src/db/schema.ts
pnpm db:migrate:local # apply to the local simulated D1 used by `pnpm dev`
pnpm db:migrate:remote # apply to the real pix-db (review the migration first)Tests apply the migrations to an in-memory D1 automatically.
All routes under /v1 need Authorization: Bearer <token>. /health is public.
ADMIN_TOKEN(Worker secret) is the bootstrap admin token. Use it to create the first tokens.- Tokens are random
pix_...strings. Only their SHA-256 hash is stored inapi_tokens; the plaintext is shown once at creation. - A token with no
site_idis an admin token. A token with asite_idcan only touch that site's images. - Revoked tokens are rejected with
token_revoked.
Routes (all under /v1, bearer token required; the base path is /v1 and not /api/v1 because the stagerightlabs.com zone blocks any URL containing /api/ before it reaches the Worker) are declared with createRoute from @hono/zod-openapi, and their Zod schemas live in packages/schema, so the OpenAPI document and the types the CLI uses come from one source.
| Method | Path | Notes |
|---|---|---|
| POST | /images |
Multipart: file, site, optional tags[] (repeat the field) and alt_text. 201 for a new image, 200 with "duplicate": true for a file already stored for that site. |
| GET | /images/:id |
Record, tags and public URL. Includes soft-deleted images (see deleted_at). |
| DELETE | /images/:id |
Soft delete. ?hard=true removes the R2 object and the row (204). |
| POST | /images/:id/restore |
Clears deleted_at. |
| GET | /images |
List, newest first. Filters: site, tag, q (filename or alt text), deleted=exclude|include|only. Paginate with limit (1 to 100, default 50) and cursor. |
| PATCH | /images/:id |
JSON: alt_text (null clears), add_tags, remove_tags. |
| GET | /sites |
A site-scoped token sees only its own site. |
| POST | /sites |
Admin only. id is a slug (lowercase letters, digits, hyphens). 409 if it exists. |
| GET | /tokens |
Admin only. Never includes hashes or secrets. |
| POST | /tokens |
Admin only. Returns the plaintext secret once. Omit site_id for an admin token. |
| DELETE | /tokens/:id |
Admin only. Revokes; idempotent. |
| GET | /openapi.json |
OpenAPI 3.1 spec. Public, served at the root like /health (not under /v1). |
Behaviours worth knowing:
- Type detection uses magic bytes only (JPEG, PNG, WebP, AVIF, GIF, and PDF via
%PDF-). The client'sContent-Typeand filename are ignored, and SVG is rejected (415). The R2 key's extension comes from the detected type:{site}/{yyyy}/{ulid}.{ext}. - Size limit is the
MAX_UPLOAD_BYTESvar (default 25 MB). It is checked againstContent-Lengthfirst and enforced again while the body is read, so a missing or falseContent-Lengthcannot get past it (413). - Hashing and memory: multipart parsing buffers the file in memory, so the SHA-256 is computed from that buffer rather than while streaming to R2. At 25 MB that is well inside the Worker memory limit. R2 also verifies the upload against the hash.
- Dedupe is per site, on SHA-256. Uploading a file that matches a soft-deleted image restores it and returns it as a duplicate.
- Dimensions are read from the file header (no dependency). EXIF rotation is not applied, and AVIF reads the largest
ispebox, sowidthandheightcan benullif a header is unreadable. PDFs always havenulldimensions. - Cross-site access by a site-scoped token returns
403. For listing, a site token is pinned to its own site, and naming another site is403. - Pagination is on the image id (a ULID, so it follows creation order).
next_cursorisnullon the last page. The page size is capped at 100 because D1 allows at most 100 bound parameters per query. - Search (
q) matches the filename or alt text case-insensitively, and%and_in the term match literally. - Tags are per site, lowercase, created on first use, and kept when no image uses them any more.
- First site and token: use the bootstrap
ADMIN_TOKENtoPOST /sites, thenPOST /tokenswith that site's id. - Failures after the R2 write remove the object again, so a failed insert leaves no orphan.
One Worker serves two hostnames and keeps them apart (src/index.ts): pix.stagerightlabs.com serves images only, pix-api.stagerightlabs.com serves the API only, and any other host (including a stray workers.dev URL, which is disabled) gets a 404. Both names are the PUBLIC_HOST and API_HOST vars, and the custom domains in wrangler.jsonc routes must match them.
- Originals:
https://pix.stagerightlabs.com/{site}/{yyyy}/{ulid}.{ext}, withCache-Control: public, max-age=31536000, immutable,ETagand conditional requests (304),Access-Control-Allow-Origin: *,Cross-Origin-Resource-Policy: cross-origin,X-Content-Type-Options: nosniff, and no cookies. Only GET, HEAD and OPTIONS are allowed. - PDFs: served inline by default (
Content-Disposition: inline). Append?downloadto the URL forContent-Disposition: attachment. PDFs are never resized or converted. - Resized or converted:
https://pix.stagerightlabs.com/cdn-cgi/image/width=800,quality=80,format=auto/{key}. Build these withtransformUrl()from@pix/schema, which keeps option order fixed (so equal requests share one cache entry) and never emitswidth=auto(each distinct width is billed as its own transformation). - Format caveat: Cloudflare serves
format=webporformat=avifonly when the request'sAcceptheader says the client supports it (otherwise you get the original format). Browsers do, so it works in practice; plaincurldoes not unless you send-H 'Accept: image/webp'.format=autopicks the best supported format, andformat=jpegorpngare always honored. - Client sites need
img-src https://pix.stagerightlabs.comin their CSP, and should store keys or relative paths rather than full URLs.
A Worker lets the public host check D1 before serving, which soft delete needs ("soft-deleted images return 404"). A bucket's custom domain serves whatever is in the bucket and cannot make that check. The Worker also sets the cross-origin and cache headers in code instead of in dashboard rules, and only serves keys that have a live database row (an orphaned R2 object is never exposed). The cost is one Worker invocation, one D1 read and one R2 read per uncached request, which is negligible at this traffic. The Worker never handles /cdn-cgi/: Cloudflare processes those URLs in front of it and the Worker only sees the source-image request, so it cannot loop on itself (a Worker that re-fetches its own /cdn-cgi/image/ URL is what causes Cloudflare's error 9403).
Soft delete is checked on every request that reaches the Worker, so it hides the original URL immediately (confirmed on the live domain: the original returns 404, and POST .../restore brings it back).
It does not hide /cdn-cgi/image/... variants. Cloudflare's image resizer keeps its own cached copy of the source image, so after a soft delete it still builds and serves variants, including widths nobody has requested before, without asking the Worker. Browsers also keep immutable originals for up to a year. So soft delete means "hidden from the original URL and recoverable", not a takedown.
For a real takedown, hard-delete the image (DELETE /v1/images/:id?hard=true) and purge its URLs in the Cloudflare dashboard (Caching, Configuration, Purge Cache, Custom purge by URL), including any /cdn-cgi/image/... variants you used. Automating that purge on delete is a possible Phase 7 addition and would need a Cache Purge API token.
pnpm dev runs with --infer-origin-from-routes=false, so the Worker sees the real local host. Use localhost:8787 as the API host and 127.0.0.1:8787 as the public host; .dev.vars.example sets API_HOST and PUBLIC_HOST to match. (Tests pin the production hostnames in vitest.config.ts, so .dev.vars does not affect them.)
curl -H "Authorization: Bearer $ADMIN_TOKEN" -F file=@photo.png -F site=blog localhost:8787/v1/images
curl -i 127.0.0.1:8787/blog/2026/<ulid>.pngRun from apps/api. Nothing here is automatic: each step changes the real account.
-
Check the secret exists, or set it. The deploy fails without
ADMIN_TOKEN. Generate one and keep the printed value somewhere safe:openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' | tee /dev/stderr | pnpm exec wrangler secret put ADMIN_TOKEN(Wrangler offers to create the Worker on the first secret.) -
Migrate the real database:
pnpm db:migrate:remote -
Deploy:
pnpm run deploy(plainpnpm deployis a different, built-in pnpm command). This creates the DNS records and certificates for both custom domains. The certificates can take a few minutes; until then the hostnames may return TLS errors. -
Check the separation:
curl -s https://pix-api.stagerightlabs.com/healthreturns{"status":"ok"}, whilecurl -s -o /dev/null -w '%{http_code}\n' https://pix.stagerightlabs.com/healthreturns404. -
Create a site and upload (use the secret from step 1):
export ADMIN_TOKEN=... # the value printed in step 1 curl -s -X POST https://pix-api.stagerightlabs.com/v1/sites \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"id":"blog","name":"Blog"}' curl -s https://pix-api.stagerightlabs.com/v1/images \ -H "Authorization: Bearer $ADMIN_TOKEN" -F file=@photo.jpg -F site=blog
-
Load the original and a resized WebP using the
urlfrom step 5's response:curl -sI "https://pix.stagerightlabs.com/blog/2026/<ulid>.jpg" curl -sI -H 'Accept: image/webp' "https://pix.stagerightlabs.com/cdn-cgi/image/width=400,format=webp/blog/2026/<ulid>.jpg"
The second should return
content-type: image/webpand acf-resizedheader. If it returnscf-not-resizedor an error, see the troubleshooting notes below. -
Check soft delete:
DELETE /v1/images/<id>makes the original return404;POST /v1/images/<id>/restorebrings it back.
Originals carry Cross-Origin-Resource-Policy: cross-origin, but Cloudflare's resizer drops it from /cdn-cgi/image/... responses (it keeps Access-Control-Allow-Origin). That only matters for client sites that send Cross-Origin-Embedder-Policy: require-corp.
Tried and unresolved: a Response Header Transform Rule (Rules, Overview, Create rule, Response Header Transform Rule; when http.host eq "pix.stagerightlabs.com", set static Cross-Origin-Resource-Policy: cross-origin) was deployed and the header still did not appear on resized responses, even for a never-requested variant. Cloudflare's docs do not say whether these rules apply to /cdn-cgi/image/ responses. The Worker's own responses already carry the header, so the rule's effect cannot be seen on them. Cloudflare Trace (Rules, Trace) can show whether the rule fires for a resized URL.
Workaround, and the likely end state: on a require-corp page, add crossorigin="anonymous" to the <img> tag (the Access-Control-Allow-Origin: * header on resized images then satisfies the policy), or use Cross-Origin-Embedder-Policy: credentialless. Pages without that policy are unaffected.
- The zone blocks any URL containing
/api/at the edge, which is why the API lives under/v1. - If your machine cannot resolve
pix-api.stagerightlabs.comright after the first deploy, it is probably caching the earlier "no such name" answer. Wait a few minutes, or test withcurl --resolve pix-api.stagerightlabs.com:443:<ip from dig @1.1.1.1>.
cf-not-resizedwith anerrvalue: the header names the reason (for example, transformations not enabled for the zone in Images, Transformations).- Error
9403: Cloudflare detected a request loop. The Worker must not fetch its own/cdn-cgi/image/URL, and does not. 404on the transformed URL only: the source-image request is being refused, so first confirm the original URL loads.
Logs and request ids. Every API response carries X-Request-Id, and the Worker logs one JSON line per request (requestId, method, path, status, ms, tokenId). A 500 body also includes request_id, and its error detail is logged under the same id. Watch live with pnpm --filter @pix/api exec wrangler tail pix-api --format json.
Rate limit. /v1 allows 300 requests per minute per client IP (the RATE_LIMITER binding in wrangler.jsonc); beyond that the API answers 429 rate_limited with Retry-After: 60. Public image serving is not limited. Change limit in wrangler.jsonc and redeploy.
Backup. Two things hold state:
# D1 (records, tags, token hashes)
pnpm --filter @pix/api exec wrangler d1 export pix-db --remote --output pix-db-$(date +%F).sql
# R2 (the image files): any S3-compatible sync tool works, for example rclone with an R2 API token
rclone sync r2:pix-images ./pix-images-backupKeep the D1 export private: it contains token hashes. Restoring is wrangler d1 execute pix-db --remote --file <export>.sql into an empty database.
Restoring a soft-deleted image. pix list --deleted only finds it, pix restore <id> brings it back. Soft delete only hides the original URL; it never removes the file.
Rotating tokens. pix tokens create <name> [--site <slug>] (run it with ! in Claude Code so the secret stays out of the chat), switch the client over, then pix tokens revoke <id>. pix tokens list shows last used, which tells you whether a token is still in use. To rotate the bootstrap admin secret: pnpm --filter @pix/api exec wrangler secret put ADMIN_TOKEN, then pix login with the new value.
apps/cli builds to one self-contained file, dist/pix.js, that bundles its dependencies.
Install (once, then again only if the path changes):
pnpm install
pnpm --filter @pix/cli build
pnpm add --global link:$PWD/apps/cli
pix --versionThis symlinks pix into pnpm's global bin directory (~/.local/share/pnpm/bin), which the dotfiles already put on PATH (profile.d/207-path-node.sh). After changing the CLI, run pnpm --filter @pix/cli build and the command is updated. (pnpm link --global no longer exists in pnpm 12; plain pnpm link only links a package into another project.)
Log in once, with a prompt that does not echo the token:
pix login # API URL (default https://pix-api.stagerightlabs.com), then the tokenIt checks the credentials against the API, then saves ~/.config/pix/config.json with mode 0600 ($XDG_CONFIG_HOME/pix/config.json if set). PIX_API_URL and PIX_TOKEN override the file one by one. Day to day, prefer a site-scoped token over the admin one: pix tokens create blog-laptop --site blog, then pix login with the secret it prints.
| Command | What it does |
|---|---|
pix upload <files...> --site <site> [--tag a,b] [--alt "..."] [--concurrency n] |
Uploads files (quote globs so pix expands them), 3 at a time by default, and prints one URL per file on stdout. Progress, duplicates and failures go to stderr. |
pix list [--site] [--tag] [--q] [--limit] [--cursor] [--deleted exclude|include|only] [--all] |
Lists images, newest first. |
pix info <id> |
Shows one image's details. |
pix tag <id> --add a,b --remove c |
Adds and removes tags. |
pix alt <id> "text" or pix alt <id> --clear |
Sets or clears alt text. |
pix rm <id> [--hard] / pix restore <id> |
Soft delete (recoverable) or permanent delete, and undo a soft delete. |
pix url <id> [--width N] [--height N] [--fit mode] [--quality N] [--format auto|webp|avif|jpeg|png] |
Prints the file URL, resized or converted if you ask (images only). --download adds ?download. |
pix sites list / pix sites create <id> [--name] |
Lists sites; creates one (admin). |
pix tokens list / create <name> [--site] / revoke <id> |
Manages tokens (admin). The secret is shown once. |
Every command takes --json (after or before the command name). Exit codes: 0 success, 1 error (including a partial upload failure), 2 usage error. Errors read Error: <message> (<api error code>); with --json they are {"error":{"code","message"}} on stderr, so stdout is always clean JSON or nothing.
Notes:
pix urlbuilds the URL from the image record, so the public host always comes from the server's configuration. The resized form needs the browser'sAcceptheader to get WebP or AVIF (see "Format caveat" above);--format autois the usual choice.- Failed
GETrequests are retried twice (a single transient500was seen once on the live API); writes are never retried. - Uploading a file that already exists for the site reports
duplicateand prints the existing URL. - The client parses every response with the shared Zod schemas in
@pix/schema, so an API change the CLI has not caught up with fails withbad_responseinstead of printing wrong data.
Already done for the Stage Right Labs account. To repeat it elsewhere:
wrangler login. With several accounts, setaccount_idinapps/api/wrangler.jsoncorCLOUDFLARE_ACCOUNT_ID.- Create the bucket:
wrangler r2 bucket create pix-images - Create the database:
wrangler d1 create pix-db, then put itsdatabase_idinwrangler.jsonc. - Enable Image Transformations on the zone (dashboard: Images, Transformations).
- Generate and set the admin secret:
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' | tee /dev/stderr | wrangler secret put ADMIN_TOKEN(note the printed value somewhere safe). The Worker deploy fails if the secret is missing. - Apply migrations to the remote database:
pnpm --filter @pix/api db:migrate:remote - The custom domains for
pixandpix-apiare declared inwrangler.jsoncand created on deploy. See Deploying, above.
Bindings: IMAGES (R2 bucket pix-images) and DB (D1 database pix-db).
apps/api: Hono Workerpackages/schema: shared Zod schemasapps/cli: thepixCLIapps/ui: web UI (Phase 8, not started)
- pnpm blocks dependency build scripts by default.
pnpm-workspace.yamlallowsesbuildandworkerd, which Wrangler needs. - Tests use
@cloudflare/vitest-plugin. Its predecessor,@cloudflare/vitest-pool-workers, is deprecated and its bundled runtime lags behind current compatibility dates.
Releases are automated with release-please. The whole repo has one version (root package.json) and one CHANGELOG.md.
- Merge PRs to
mainwith Conventional Commit titles (the squash commit message is the PR title). - release-please keeps a "chore(main): release x.y.z" PR open that bumps the version and updates
CHANGELOG.md.featbumps the minor version,fixandperfbump the patch version, and!or aBREAKING CHANGE:footer bumps the major version (while below 1.0.0, breaking changes bump the minor version instead). - Merging that PR creates the
vx.y.ztag and GitHub Release. Deploying is still manual (pnpm run deploy).
The workflow authenticates with the RELEASE_PLEASE_TOKEN repository secret, a fine-grained PAT with Contents and Pull requests read/write on this repo. It is a PAT rather than GITHUB_TOKEN so the release PR triggers the required check-title check. If the token expires, release PRs stop updating.
This project uses Conventional Commits (with scope) for commit messages and pull request titles. This clarifies the work done in each commit and allows changelogs to be generated for releases.
The format is type(scope): description. For example:
feat(lambda): add new lambda function to handle data processingFor the type of work please use one of the following:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)refactor: A code change that neither fixes a bug nor adds a featureperf: A code change that improves performancetest: Adding missing tests or correcting existing testschore: Changes to the build process or auxiliary tools and libraries