Configuration

A Diffinery instance is configured in four places: Worker variables in apps/diffinery/wrangler.jsonc, Worker secrets set with wrangler secret put, the Cloudflare bindings in the same wrangler.jsonc, and the secrets and variables of the repository whose workflows deploy it. This page lists every setting, its default and what it changes. To deploy for the first time, follow Deploy your own Diffinery.

#Where configuration lives

#Worker variables

Set under vars in wrangler.jsonc. All values are strings.

When either ACCESS_TEAM_DOMAIN or ACCESS_AUD is empty, email sign-in at /auth/access is off: the page answers "Account recovery by email is not set up on this instance. Ask an administrator for a sign-in link.", and the sign-in page doesn't offer Recover your account by email. Passkeys, invitations and admin sign-in links keep working, but the first administrator can't sign in, because email sign-in is how an account in BOOTSTRAP_ADMINS is created.

#PUBLIC_URL

PUBLIC_URL must be the exact origin people and tools use, with https:// and no path. You don't set it by hand for a deploy: scripts/render-config.mjs sets it from --public-url, which bootstrap fills in as https://<DIFFINERY_DOMAIN>, and refuses a URL that isn't https:// or has a path (--public-url must be an https origin, like https://git.example.com). The same flag points the Worker's route at that hostname, so the route and PUBLIC_URL always agree. Diffinery uses it for:

• Passkeys. The WebAuthn relying party ID is the hostname of PUBLIC_URL, and the expected origin is its origin. Passkeys only work on that hostname.
• Every generated link: emails, invitation and sign-in links, html_url and clone_url in API responses, webhook payloads, check run details links, the sitemap and canonical tags.
• Workflows: github.server_url is PUBLIC_URL, github.api_url is PUBLIC_URL/api/v3, and the runner agent and sandboxes call back to it.
• OIDC: the issuer (iss) of workflow ID tokens, and their default audience.
• The container registry host name, the hostname of PUBLIC_URL (images are <hostname>/<owner>/<name>).
• The cross-site check: a cookie-authenticated write with an Origin other than this origin is refused.

Important: Changing PUBLIC_URL on a running instance (by deploying with another DIFFINERY_DOMAIN) breaks every existing passkey (they are bound to the old hostname), changes the OIDC issuer that cloud providers trust, and changes every image name. Choose the hostname before your first sign-in.

#BOOTSTRAP_ADMINS

A comma-separated list of email addresses; spaces around entries are ignored and matching is case-insensitive. Logins in the list are ignored, because anyone could pick a free login, while an email address has to be proven (by email sign-in or by opening the link in an invitation email).

You don't keep the list in the repository. Each deploy sets it (scripts/bootstrap-admins.sh, run by bootstrap), from the first of these that isn't empty:

With none of them (a brand-new instance), the deploy warns that nobody will become a site administrator. If the Worker's settings can't be read, the deploy stops instead of replacing its list with an empty one. The deploy logs say how many addresses it set, never the addresses.

An account becomes a site administrator from this list only when it is created (through email sign-in at /auth/access, by joining from an invitation or through open sign-up, or through DEV_AUTH locally), or when an account that is still waiting for an invite signs in through /auth/access. Accounts that already exist are not promoted or demoted when you change the list later, and there is no page for granting or removing site administration. See Site administration.

#SIGNUP

With SIGNUP=open, the sign-in page links to Create an account (/signup). Someone enters their email address, gets a 6-digit code by email, enters it, picks a username and creates a passkey; their account is active at once (see Open sign-up). Unset, or any other value, the instance is invite-only as before: /signup answers 404 and the sign-in page says so.

Open sign-up needs Cloudflare Turnstile, so scripts can't use it to send email. The deploy sets Turnstile up (see Turnstile), so to open sign-up add "SIGNUP": "open" under vars in wrangler.jsonc; the deploy keeps it. The Turnstile keys alone never open sign-up: only SIGNUP=open does.

Each code request is checked with Turnstile's siteverify API, with the visitor's IP address. Without both keys, /signup answers 503 with "Sign-up needs Turnstile configured", except when PUBLIC_URL is on the local machine (localhost, 127.x.x.x or [::1]): local development and the end-to-end tests skip the check. Only the sign-up page's and the security report form's content security policy allows scripts and frames from https://challenges.cloudflare.com.

The limits on codes (5 a day per address, 20 a day per IP address, 10 minutes and 5 tries each) are in Limits. Sign-up emails always send: they need the EMAIL binding and the MAIL queue like every other email.

#EGRESS

Experimental: web hasn't been tried on a live instance yet. The setting covers the whole instance, so try it on a test instance first, or check it with an account no site administrator runs, as in Check it below. diffinery.com doesn't set it.

With EGRESS=web, hosted job and sandbox containers start without direct internet access. Cloudflare then lets only ports 80 and 443, and DNS to Cloudflare's resolvers, leave the container, and Diffinery forwards HTTP and HTTPS requests to any host through the Worker. Unset, or any other value, hosted compute reaches the whole internet as before. The setting is read when a container starts: jobs and sandboxes already running keep the access they started with.

Under web:

• Works: git clone https://..., curl, apt-get, npm, pnpm and pip installs, docker pull, and calls to the Diffinery and GitHub APIs.
• Refused: every other port. That includes SSH (git@... remotes, ssh, scp), SMTP (25, 465 and 587), IRC, databases and HTTP on other ports.
• HTTPS is intercepted. Requests leave through the instance's own Worker, which sees them decrypted, as the operator already can for the container itself. Cloudflare re-signs them with a CA it puts in the container at /etc/cloudflare/certs/cloudflare-containers-ca.crt. The runner agent adds that CA to the system store and sets NODE_EXTRA_CA_CERTS and REQUESTS_CA_BUNDLE, so tools that use the system store, Node.js and Python's requests trust it. Tools with their own fixed CA list or certificate pinning, client certificates (mutual TLS), and HTTPS from inside Docker containers a job starts (docker run, services:, RUN steps of a build) fail their certificate checks.

The account that owns the repository decides, as for quotas. Accounts run by a site administrator (their own account, and organizations with a site administrator as an owner) stay open even with EGRESS=web, so the instance's own Deploy and live test workflows keep their access. Self-hosted runners and GitHub imports are not affected. Under wrangler dev sandboxes run in a local process, not containers, so the setting changes nothing there.

To turn it on, add "EGRESS": "web" under vars in wrangler.jsonc; the deploy keeps it. To turn it off, remove it (or set any other value) and deploy again; containers started after that are open.

#How a blocked connection looks

Diffinery doesn't add a line to the job or terminal output when it limits a connection. The tool that made it reports an ordinary network error:

• A port other than 80 or 443 fails to connect, as behind a firewall: for example ssh: connect to host github.com port 22: Connection refused (or Connection timed out), or a mail or database client that can't reach its server.
• HTTPS from a tool that doesn't trust the Cloudflare CA fails its certificate check: for example SSL certificate problem: unable to get local issuer certificate (curl), x509: certificate signed by unknown authority (Go), PKIX path building failed (Java), or self-signed certificate in certificate chain (Node.js with its own CA list). Inside a Docker container a job starts, add the CA from /etc/cloudflare/certs/cloudflare-containers-ca.crt to the image, or run that step on the host.

If the CA never appears in the container, the runner agent writes web-only egress, but /etc/cloudflare/certs/cloudflare-containers-ca.crt did not appear: HTTPS will fail to the container's own log (not the job log), and every HTTPS request from the job fails its certificate check.

#Check it

With EGRESS=web deployed, run a workflow in a repository owned by an account that no site administrator runs (a site administrator's own repositories stay open):

on: workflow_dispatch
jobs:
  egress:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsSI https://example.com            # works
      - run: git ls-remote https://github.com/git/git HEAD   # works
      - run: npm view left-pad version                 # works
      - shell: bash
        run: "! timeout 10 bash -c '</dev/tcp/github.com/22'"  # SSH port: must not connect

All four steps pass. The last one fails if port 22 is reachable, which means the account is open (a site administrator runs it) or the setting isn't deployed.

#Security contact

/.well-known/security.txt (RFC 9116) tells security researchers where to report a problem. Diffinery always serves it, with:

The report form needs no setup: reports go to the instance's site administrators, who each get an email with the report's summary and read it under Settings → Security reports (see Site administration). People who are signed in can always send one. People who aren't pass Cloudflare Turnstile first, with the same TURNSTILE_SITE_KEY and TURNSTILE_SECRET as open sign-up, which the deploy sets up (see Turnstile; you don't need SIGNUP=open for this). Without both keys, for example when the deploy's API token lacks Account → Turnstile → Edit, the form asks visitors to sign in, except on the local machine, where the check is skipped as for sign-up.

SECURITY_CONTACT is optional. Use an address someone reads. The repository leaves it unset on purpose, so an instance never advertises an address its operator didn't choose. To add one, add "SECURITY_CONTACT": "security@example.com" under vars in wrangler.jsonc; the deploy keeps it.

#Turnstile

The security report form, and open sign-up when it's on, check with Cloudflare Turnstile that a visitor without an account is a person. Every deploy sets it up (scripts/turnstile.sh, run by scripts/bootstrap.sh):

1. It looks for a Turnstile widget named diffinery <DIFFINERY_DOMAIN> in the account, and creates one when there is none: managed mode, for your hostname only.
2. The widget's site key becomes the TURNSTILE_SITE_KEY variable of the deployed Worker.
3. Its secret key becomes the TURNSTILE_SECRET secret: scripts/ensure-secrets.sh sets it when it's missing, and bootstrap replaces it before the deploy when it goes with another widget (the deployed TURNSTILE_SITE_KEY is not this widget's, for example because the widget was deleted and created again). The key goes from the Cloudflare API straight to wrangler secret put and is never printed.

The deploy's API token needs Account → Turnstile → Edit for this (the API reference calls it "Turnstile Sites Write"). Without it the deploy warns, naming the permission, and goes on; people who aren't signed in then can't send security reports until you add it and deploy again.

To use a widget of your own instead, add "TURNSTILE_SITE_KEY": "<site key>" under vars in wrangler.jsonc and store its secret key with printf '%s' "$TURNSTILE_SECRET" | pnpm exec wrangler secret put TURNSTILE_SECRET -c wrangler.deploy.jsonc. The deploy then creates no widget and never replaces your secret; it only fills in a missing TURNSTILE_SECRET when your widget is in the same Cloudflare account. If you rotate the secret key of the deploy's widget in the dashboard, run pnpm exec wrangler secret delete TURNSTILE_SECRET -c wrangler.deploy.jsonc and deploy again, so the deploy stores the new one.

#DEV_AUTH

When DEV_AUTH is set, ACCESS_AUD is empty and both PUBLIC_URL and the request's own address are on the local machine (localhost, 127.x.x.x or [::1]), every request without credentials (no token, no session) acts as the account with the email in DEV_AUTH, with full access. That account is created on first use and is a site administrator if the email is also in BOOTSTRAP_ADMINS. While DEV_AUTH is set, the email log also keeps each whole message, and GET /api/v3/diffinery/emails returns it, so tests can read emails without delivering them.

Important: Never set DEV_AUTH on a deployed instance. As a safeguard it does nothing there: a request that reaches the Worker under any other host name, such as workers.dev or your domain, or a PUBLIC_URL that isn't on the local machine, turns it off, and so does Cloudflare Access.

#Worker secrets

Set with wrangler secret put (the deploy does this for you with scripts/ensure-secrets.sh), never in wrangler.jsonc.

None of these secrets is rotated automatically, and ensure-secrets.sh never replaces one that exists. Keep a copy of MASTER_KEY somewhere safe: replacing it without keeping the old one as MASTER_KEY_PREV makes every stored secret undecryptable and invalidates unsubscribe links already sent, along with the runtime tokens of running jobs and cache and artifact links already handed out. To rotate it, follow Rotating MASTER_KEY. To rotate the OIDC key, delete OIDC_PRIVATE_KEY and deploy: a new key with a new kid (diffinery-<date>) is generated, and relying parties pick it up from /.well-known/jwks.

To set a secret by hand (for example to restore a backup):

cd apps/diffinery
printf '%s' "$MASTER_KEY" | pnpm exec wrangler secret put MASTER_KEY -c wrangler.deploy.jsonc

#Rotating MASTER_KEY

Rotate MASTER_KEY when it may have leaked, or on your own schedule. Diffinery accepts two keys while a rotation is under way: MASTER_KEY, which encrypts and signs everything new, and MASTER_KEY_PREV, the key it replaced, which is only used to decrypt and verify what was made before.

1. Make a new key and keep it with your copy of the current one:

   NEW_KEY="$(openssl rand -base64 32)"

2. Set the current key as MASTER_KEY_PREV and the new one as MASTER_KEY in one step, so no version of the Worker runs with the new key alone. OLD_KEY is the current value from your safe copy (Cloudflare doesn't show a secret's value):

   cd apps/diffinery
   jq -n --arg old "$OLD_KEY" --arg new "$NEW_KEY" '{MASTER_KEY_PREV: $old, MASTER_KEY: $new}' | pnpm exec wrangler secret bulk -c wrangler.deploy.jsonc

   To use wrangler secret put instead, put MASTER_KEY_PREV first and MASTER_KEY second: each command deploys a new version of the Worker, and a version with the new MASTER_KEY but no MASTER_KEY_PREV can't read the secrets stored so far.

3. Save the new key where you kept the old one. Nothing else needs to change: no deploy, migration or restart.

From then on:

• New and replaced secrets (repository, organization and environment secrets, model provider keys, webhook secrets, import tokens) are encrypted with the new key. Each stored value names the key it was encrypted with (v2.<key id>.…, where the key id is the first 8 hex characters of the key's SHA-256: printf %s "$NEW_KEY" | base64 -d | sha256sum | cut -c1-8). Values stored before key ids existed (v1.…) are tried with both keys.
• Stored values move to the new key by themselves as they are used: repository, organization and environment secrets the next time a workflow job uses them, model provider keys the next time an agent task does, webhook secrets the next time the webhook delivers, and the GitHub token of an import when the import is retried. A value nothing uses stays encrypted with the old key until someone saves it again.
• Unsubscribe links, invitation and verification emails, sign-up codes, GitHub linking codes and OAuth state, runtime tokens, cache and artifact URLs, and image proxy URLs in pages already rendered signed with the old key keep working; new ones are signed with the new key.

Remove MASTER_KEY_PREV (pnpm exec wrangler secret delete MASTER_KEY_PREV -c wrangler.deploy.jsonc) only when nothing you still need depends on the old key:

• Every repository, organization and environment secret and every model provider key you still need has been used or saved again since the rotation. Secrets your workflows use every day move over by themselves; one that only a rare workflow uses (a release, a yearly job) may not have, and its value can't be read back, so whoever manages it re-enters it. One left behind can't be decrypted once MASTER_KEY_PREV is gone, and runs that use it fail.
• Links already sent have expired, or you accept that they stop working: runtime tokens and cache and artifact URLs last about as long as their job, sign-up codes 10 minutes, image proxy URLs until pages and browsers cache them no more (at most 7 days), verification links 24 hours, invitation emails until the invitation expires, and unsubscribe links up to a year. Someone with an old unsubscribe link can still change their email settings after signing in.

If the old key leaked, treat the secrets as exposed: replace their values at the source (new API tokens, new passwords) and save the new values, which are sealed with the new key. Then remove MASTER_KEY_PREV right away: until then, anyone holding the old key can still forge what it signs.

#Bindings

Defined in wrangler.jsonc. The deploy creates the underlying resources if they don't exist.

The Durable Object classes are declared in six migrations (new_sqlite_classes): tag v1 for RepoDO, RunnerContainer and SandboxContainer, tag v2 for ImportContainer, tag v3 for ProjectDO, tag v4 for SchedulerDO, tag v5 for RunnerContainerMedium, RunnerContainerSmall and RunnerContainerTiny, and tag v6 for ComposeDO. wrangler deploy applies a migration tag the account doesn't have yet.

#Other Worker settings

#The dev environment

wrangler.jsonc has an env.dev section that pnpm dev (wrangler dev -e dev) and the end-to-end tests use. It is removed from the deployed config.

To run an import locally, start it as usual, wait until its git.phase is waiting, claim the transfer, and run the runner agent's import mode against your instance (build it first with pnpm -r build):

TOKEN=$(curl -sS -X POST http://localhost:8787/api/v3/diffinery/imports/<id>/claim | jq -r .token)
DIFFINERY_API_URL=http://localhost:8787 DIFFINERY_IMPORT_ID=<id> DIFFINERY_IMPORT_TOKEN=$TOKEN \
  DIFFINERY_WORK_ROOT=/tmp/diffinery-import node containers/runner/dist/agent.mjs

Only the account that started the import can claim it. In local development (DEV_AUTH in effect, as described in DEV_AUTH), imports also accept plain http:// and loopback GitHub API URLs, for test doubles.

MASTER_KEY is not set in dev. Add it to apps/diffinery/.dev.vars (MASTER_KEY=<base64 of 32 random bytes>) or pass --var MASTER_KEY:<value> to wrangler dev to store Actions secrets locally. The end-to-end tests pass a random one with --var, together with PUBLIC_URL.

#GitHub imports

Imports from GitHub need no setup beyond a normal deploy: the IMPORTER container, the IMPORT_WORKFLOW Workflow and the D1 tables of migration 0010_imports.sql are created by the deploy. What you can tune:

To offer linking through GitHub sign-in, create an OAuth app on github.com (Settings → Developer settings → OAuth Apps) with the authorization callback URL https://git.example.com/settings/linked/github/callback (your PUBLIC_URL plus /settings/linked/github/callback). Then add the client ID under vars in wrangler.jsonc and store the secret:

cd apps/diffinery
printf '%s' "$CLIENT_SECRET" | pnpm exec wrangler secret put GITHUB_OAUTH_CLIENT_SECRET -c wrangler.deploy.jsonc

The OAuth flow asks GitHub for the read:user scope only, uses github.com (not an Enterprise host), and binds its state to the signed-in account. Without the two settings, people link accounts with the gist code, which needs no configuration.

Imports reach GitHub only on HTTPS hosts with public names; a GitHub API URL on a private address, localhost, .local or .internal is refused with 422 github_api_url must be a public host.

#Deploy script settings

Environment variables the scripts in scripts/ read. scripts/setup.sh reads all of them too, asks for CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, DIFFINERY_DOMAIN and BOOTSTRAP_ADMINS in a terminal when they aren't set, and requires DIFFINERY_DOMAIN (see Deploy from your own machine):

scripts/render-config.mjs takes flags instead:

Bootstrap calls it with --public-url https://$DIFFINERY_DOMAIN, --zone $DIFFINERY_ZONE when that is set, --mail-from notifications@${MAIL_DOMAIN:-$DIFFINERY_DOMAIN} and --admins with the list scripts/bootstrap-admins.sh picked. See Deploy your own Diffinery.

#Repository secrets and variables for the workflows

The workflows in .github/workflows/ read these from the repository (or its production environment):

Deploy reads DIFFINERY_DOMAIN, DIFFINERY_ZONE and MAIL_DOMAIN from the repository's variables and passes them to bootstrap, so you point it at your own hostname without editing the workflow (see Deploy your own Diffinery). Deploy runs on pushes to main on any Diffinery instance, and when started by hand on GitHub.

The Deploy job runs in an environment named production (created by its first run, with no branch policy). The Live test checks the upstream project's public instance, https://diffinery.com, and runs on its own after a deploy only there; delete it, or change its DIFFINERY host, for your own instance.

When agents land changes on main. A merge that Diffinery lands for an agent through auto-merge is the agent's push, so the Deploy and Live test runs after it are runs of agent code. Those get no repository or organization secrets, and Deploy stops with CLOUDFLARE_ACCOUNT_ID is required. Either keep the secrets in the production environment, limited to protected branches, with main protected (add environment: production to the Live test job as well), or have an admin turn on Give runs of agent code the repository's and organization's secrets under Settings → Actions. The environment is the tighter choice: the setting gives the secrets to every agent run, branches included. See Which runs receive secrets.

scripts/diffinery-wait-runs.sh waits for the Actions runs on a commit. It reads DIFFINERY (the instance origin) and TOKEN (a Diffinery token) from the environment:

DIFFINERY=https://diffinery.com TOKEN=dfy_... scripts/diffinery-wait-runs.sh acme/website <sha> 60

#Settings that are not configuration

Some values are fixed in code and can't be changed without editing it, for example the job timeout ceiling, matrix size, the 10 GB cache budget per repository and session lifetime. They are listed in Limits.