Secrets, Gateway settings and capabilities

The three places a value can live

The deploy itself also sets two secrets on every one of the app's Workers with cf deploy --secrets-file: GATEWAY_URL and EVERY_APP_ORG_ID. They are not the app's to set, and secret list hides them unless --verbose.

everyapp configure <app>

pnpm everyapp configure <app> is the one command that sets up an app (packages/cli/src/commands/configure/index.ts). It reads what the app's manifest declares (its AI providers, capabilities and own secrets) and what is set, asks for each setting that isn't, and sets everything where it belongs in one go. secret set stays for one name at a time and for scripts (below).

Named, the app is read from the registry (the manifest its last deploy stored), so the command runs from any directory; an app never deployed is refused with APP_NOT_FOUND (<app> isn't deployed to this Gateway then An app is configured by name after its first deploy; in its directory, configure works before that too (for the Gateway's settings). Nothing was changed.; rerun pnpm everyapp status); a registered row whose first deploy never finished (status: "pending") counts as undeployed, by name and in its directory. Without a name it reads the everyapp.config.ts in the current directory, deployed or not: before the first deploy only the Gateway's settings can be set, and the app's own wait for the deploy. Neither: MANIFEST_NOT_FOUND (No everyapp.config.ts in this directory, and no app named; fix name the app: pnpm everyapp configure <app> (pnpm everyapp status lists them), or run this from its directory). The Gateway is reached (login and account as every Gateway command) before anything is asked.

At a terminal

One dim line says where the values go: <app>'s settings are held as the Gateway's secrets: an AI key or a capability's client on the Gateway Worker, once for every app; <app>'s own secrets on its Worker. Changes are live at once, no deploy needed. Then the SETTING / WHERE / STATUS table secret list prints (names only, never values; before the first deploy the app's own rows read after first deploy; an app with no rows: <app> declares no secrets and needs no Gateway settings.). Then the prompts, for whatever --from-env (below) didn't cover (piped stdin means no terminal, so the lines on it never meet a prompt):

• A hidden prompt per required setting that is unset, in manifest order, with what status says about the setting above its first name: <Label>: <why>, the provider's hint (what the key is and where it comes from), Get it at <docs> when the registry or manifest knows where, and Guide: .claude/skills/everyapp/setup/<name>.md when it has a guide (Guide: pnpm everyapp provider show <id> for a provider registered on the Gateway). A plain setting (EMAIL_FROM and the others under Plain settings are shown and checked) gets a visible prompt with Takes … above it and is checked as typed. A setting with several names (an OAuth client: GOOGLE_WORKSPACE_CLIENT_ID + GOOGLE_WORKSPACE_CLIENT_SECRET) reads unset while one name is missing, and only the missing name is asked for.
• Which <group>? One is enough. for an unmet any-of group whose members can be set now (a menu of their labels; one member only, or one already covered: no question), then the chosen member's value. A group one member already meets asks nothing; its other members are offered with the optional ones.
• Set the N optional settings too? (Set the optional setting too? for one), the unmet optional settings named under it, No by default: one keystroke skips them all. Yes asks for each as NAME (Enter to skip); Enter skips that one.

An app that is ready gets a menu instead, Everything <app> needs is set. Change one?, listing every setting that can be set now (NAME, or ID + SECRET for a pair, with its label and status as the hint) and No, done; a chosen setting is asked for as above, until No, done. An app that declares nothing is done at once. Ctrl-C at any prompt is CANCELLED: Cancelled. Nothing changed.

Everything is applied at the end, in one go, through the machinery secret set uses (the leases, the replaceable-version check, one cf workers secrets bulk call per Worker, the version recorded as everyapp's own, the app's secret names recorded on its row; all under Where everyapp secret set NAME puts a name): one new Worker version per destination, the Gateway's first. Steps secrets.gateway and secrets.app end Set A and B on the Gateway and Set C on <app>. Live at once; no deploy.

Flags of configure

How the values get in

A value never goes on the command line. pnpm everyapp configure NAME=value is refused before anything is read, VALUE_ON_COMMAND_LINE: NAME=… looks like a value on the command line, which configure never takes then It lands in the shell's history and the process list: rotate it if it was real. Nothing was set.; fix pipe NAME=value lines in (one per line), or export NAME and add --from-env. A second argument (pnpm everyapp configure crm OPENAI_API_KEY=sk…) never reaches the command: the argument parser refuses it as TOO_MANY_ARGUMENTS, configure takes one argument, but got another: "OPENAI_API_KEY=…" then A value never goes on the command line: it lands in the shell's history and the process list. Rotate it if it was real. (the input is cut at its =); --from-env=<anything> is INVALID_VALUE, --from-env is a switch and takes no value then the same line, and what followed the = is never shown. Three sources, which don't all combine: --from-env fills what it can and the prompts cover the rest; the lines on stdin combine with nothing (piped stdin means no terminal, and with --from-env stdin isn't read):

1. The prompts above, when a person can be asked (stdin and stderr are terminals, not --json, CI unset: canPromptInTerminal).
2. NAME=value lines on stdin, one per line (parsePipedLines in packages/cli/src/commands/configure/index.ts): what a command produced, or a file the person wrote. Blank lines and lines starting with # are skipped; an export prefix is allowed; one pair of matching quotes (' or ") around the value is dropped; the value is otherwise taken as it is (a # or an = inside it is part of it); a later line for the same name wins. Every name given is set, set already or not; a name a capability reads once set (EMAIL_FROM_NAME, EMAIL_PROVIDER, RESEND_API_KEY and EMAIL_REST_API_TOKEN for email) is taken too, though never prompted for. Each line is checked before anything is written: a line that isn't NAME=value is PIPED_LINE_INVALID (Line <n> of the piped input isn't NAME=value then Nothing was set.; fix pipe NAME=value lines, one per line; a bare value goes to pnpm everyapp secret set NAME; the line is never echoed, since the echo "$KEY" | … habit pipes a bare secret); a name the manifest doesn't declare is SECRET_NOT_DECLARED (<app> doesn't declare NAME when the name looks like one, upper snake case; otherwise <app> doesn't declare line <n> (not shown: it may be a value); then The piped lines set what its deployed manifest lists (a provider, a capability or one of its secrets). Nothing was set., its everyapp.config.ts lists in the app's directory; fix leave it out, or declare it in everyapp.config.ts; a bare value goes to pnpm everyapp secret set NAME, by name … declare it in everyapp.config.ts and deploy again; …); a blank value is SECRET_EMPTY (NAME is empty in the piped lines; fix give NAME a value, or leave the line out); a plain setting's value the Gateway wouldn't read is SETTING_VALUE_INVALID, as from secret set; one of the app's own before its first deploy is APP_NOT_FOUND (<app> isn't deployed yet then Its own NAME can be set after its first deploy. Nothing was set.; rerun pnpm everyapp deploy).
3. --from-env, above: the unset names only, stdin left unread.

Stdin and --from-env are how a script or a coding agent, which can't answer a prompt, gets values in. Under --json (in CI, or without a terminal) with nothing piped, no --from-env variable found and a required setting unset, the run stops with SECRET_VALUE_REQUIRED: Can't ask for <app>'s settings without a terminal then <app> needs <names>. Run this at a terminal, pipe NAME=value lines in (one per line), or export them under those names and add --from-env (which also takes the variable of any unset optional setting).; data.names the names still missing (each required one and the first member of each unmet group; of a pair with one name set, only the other). The rerun is pnpm everyapp configure <app> --from-env (rerunNote with the variables exported) once the app is deployed; before its first deploy it is pnpm everyapp configure --from-env (in the app's directory, with the variables exported), since the name form is refused for an undeployed app.

pnpm everyapp configure crm                                                        # a person, at a terminal
printf 'OPENROUTER_API_KEY=%s\n' "$OPENROUTER_API_KEY" | pnpm everyapp configure crm --json
pnpm everyapp configure crm --from-env --json                                      # every exported name at once

What it says at the end

done with message Set A, B and C. <app> is ready (the names in manifest order, whatever order they came in; <app> is ready alone with nothing to set) and data: { app: { id, deployed, setup }, set: string[], changed?: { gateway?: { names, versions }, app?: { id, workerName, names, versions } }, next? }: setup the AppSetup of /docs/agent/json, read again after the change; set the names set; changed as secret set's data, absent when nothing was set. An app still not ready gets the warning APP_NEEDS_SETUP that deploy and status give (step app.secrets, <app> won't open until <names> is set, data.setup; the names are the ones still missing, so a pair with one name set names the other), the message Set A. <app> still needs X and next: [{ command: "pnpm everyapp configure <app>", note: "at a terminal, with NAME=value lines on stdin, or with --from-env" }] (before the first deploy, { command: "pnpm everyapp configure", note: "in the app's directory: at a terminal, with NAME=value lines on stdin, or with --from-env" }). An app not deployed yet, whose Gateway settings are now set, gets no warning (its own read as unknown until its Worker exists): Set A and B. <app>'s Gateway settings are set; its own X and Y come after its first deploy with next: [{ command: "pnpm everyapp deploy", note: "then pnpm everyapp configure <app> for X and Y" }] (an app with no secrets of its own: <app>'s Gateway settings are set, note in the app's directory). A failure after one destination already changed is SECRETS_PARTIALLY_APPLIED, with the message and data: { applied, left } of secret set (below) but rerun pnpm everyapp configure <app> (rerunNote to set what is left; before the first deploy pnpm everyapp configure, in the app's directory, to set what is left), retryable: run again, it reads what is set and asks only for what is still missing.

setup.command (what status --json data.apps[].setup, secret list --json data.app.setup and the Gateway's app lists carry) is { command: "pnpm everyapp configure <app>" } while something is unmet, null once the app is ready; the Gateway's "Needs setup" dialog, deploy's next, status's APP_NEEDS_SETUP fix, secret list's next and the MCP instructions (needs setup: an admin runs pnpm everyapp configure <app>) all name it. The one exception is an MCP app (pnpm everyapp mcp on dataforseo: tier provider, no Worker, nothing to configure), whose command stays pnpm everyapp secret set DATAFORSEO_API_KEY.

Where everyapp secret set NAME puts a name

packages/cli/src/commands/secret/index.ts routes every name before it touches the network or asks for a value, so a refusal never costs a typed value. One call may mix Gateway settings and app secrets; each name goes where it belongs, the Gateway's first.

1. The name is in SETTABLE_GATEWAY_SETTINGS, or ends in _MCP_TOKEN (a remote MCP app's credential: REMOTE_MCP_SECRET_PATTERN, "MCP apps" below): it goes to the Gateway Worker, from any directory. The manifest in the current directory is never read for it, and neither is the registry: the family is a fixed rule (isSettableGatewaySetting in packages/sdk/src/internal/gatewaySettings.ts). A name a provider registered on the Gateway holds (a row of its providers table, Registered providers) goes there too: for a name of that shape the command connects first to ask the rows, prints whose it is and the hosts its key is sent to, and after setting it binds the row.
2. Any other name needs the app's manifest: everyapp.config.ts in the current directory (cwd), or with --app <id> the manifest the registry stored at the app's last deploy (given both, --app wins and the directory is never read). If that manifest lists the name under secrets, it goes to the app's Worker and each helper Worker. (unset also takes a name the manifest no longer lists, so a secret dropped from the manifest can still be removed; such names are reported as "NAME isn't listed in everyapp.config.ts." above the confirmation.)
3. Otherwise the call is refused, in this order:

4. The CLI then connects to the Gateway (login and account as every Gateway command; --gateway, --account-id) and, for app names, finds the app in the registry. An app that was never deployed is refused with APP_NOT_FOUND: <id> isn't deployed yet then Its secrets can be set after its first deploy. Nothing was changed.; rerun pnpm everyapp deploy.
5. Only now is each name's value read (one prompt per name, in the order given).
6. The change is applied under leases (gateway.secrets, then app.secrets; acquireGatewayLease and acquireAppLease in packages/cli/src/lib/gateway/lease.ts). While another run holds one (a deploy, setup, email set, or another secret change), the command waits up to 5 minutes, saying so as progress on gateway.lease or app.lease (Waiting for a change to the Gateway's settings to finish (<who> on <machine>, started 1m ago), Waiting for a secret change on <id> to finish (…)), then fails with LEASE_HELD before anything changes: A change to the Gateway's settings is still running after 5m or A secret change on <id> is still running after 5m (roughly() in packages/cli/src/lib/output/time.ts renders the wait as 5m), then It's from <who> on <machine>. If it stopped without cleaning up, it's released within <time>.; retryable, data.holder, rerun once it's done (pnpm everyapp status shows it). The command never calls lease.check(), so it doesn't raise LEASE_LOST; a heartbeat renews each lease every 30 seconds until it is released. For the Gateway, the install row must exist (GATEWAY_NOT_INSTALLED, rerun pnpm everyapp setup). Every target Worker is checked first (assertReplaceable in packages/cli/src/lib/cf/deploy.ts): if the version serving is not one everyapp recorded, an unattended run stops with action_required (rerun_interactive: "… was changed outside everyapp; confirm in a terminal") and a person is asked "Set NAME on it anyway?". Then one cf workers secrets bulk --worker <name> --body @<file> call per Worker makes a new version with the change (packages/cli/src/lib/cf/secrets.ts): the Gateway's Worker, then the app's Worker, then each helper. The new version id is recorded as everyapp's own (the install row's live_version_id, or the app's resource records), so the next deploy or setup replaces it unattended. No deploy happens; the secret is live at once.

Events: progress secrets.route (NAME is a Gateway setting → Worker every-app-gateway or NAME is <id>'s secret → Worker <app>, <helper>), step secrets.gateway and secrets.app (message Updating the Gateway... / Updating <id>..., then Set NAME on the Gateway; data: { action, names, versions }), progress secrets.version (<worker> is now at version <id>), and done with message Set OPENAI_API_KEY on the Gateway, and GITHUB_TOKEN on todo and data: { gateway?: { names, versions, pinned? }, app?: { id, workerName, names, versions } } (versions maps each Worker name to its new version id; pinned lists each remote MCP credential set, { name, origin }, with the one origin the Gateway now sends it to, and the message and the display add <NAME> is sent to <origin> and nowhere else. per credential). A remote MCP credential adds progress secrets.pin (<NAME> is pinned to <origin>) and may warn REMOTE_MCP_SECRET_UNDECLARED or REMOTE_MCP_SECRET_AMBIGUOUS ("MCP apps" below).

A failure after one destination already changed is SECRETS_PARTIALLY_APPLIED (retryable): Couldn't set NAME on <destination>, Cloudflare said: …, X is set; only Y is left., with rerun naming only what is left ( --app <id> added when the command ran by --app and a name of the app's own is left) and data: { applied, left }, so no value is asked for twice. Raised through configure, the same message and data come with rerun pnpm everyapp configure <app> (rerunNote to set what is left; before the first deploy pnpm everyapp configure, in the app's directory, to set what is left).

Flags of secret set

How a value is read: never the command line

packages/cli/src/lib/secretValue.ts takes a value from exactly one source, decided before anything else is checked:

With --json, in CI, or without a terminal, and no --from-env or piped value, the command fails with SECRET_VALUE_REQUIRED: Can't ask for NAME's value without a terminal then Or pipe it in: echo "$NAME" | pnpm everyapp secret set NAME; rerun pnpm everyapp secret set NAME --from-env NAME.

--from-env and a piped value hold one value, so naming several secrets with either is SECRET_SEVERAL_NAMES (--from-env sets one secret at a time, and you named 2; fix: run it once per name). The prompt asks once per name, so pnpm everyapp secret set LINKEDIN_CLIENT_ID LINKEDIN_CLIENT_SECRET works at a terminal.

Plain settings are shown and checked

A credential is never shown and never checked. A plain Gateway setting, one of PLAIN_GATEWAY_SETTINGS (isPlainGatewaySetting in packages/sdk/src/internal/gatewaySettings.ts: EMAIL_FROM, EMAIL_FROM_NAME, EMAIL_PROVIDER, EMAIL_PASSWORD_SIGN_IN, MASTODON_URL, AI_PROXY_EXTRA_ROUTES, the MCP_* switches and lists, the CLOUDFLARE_ACCESS_* names other than the OIDC client secret, HOSTED_OPEN_SIGNUP, BROWSER_APP_INSTALLS, DISPATCH_NAMESPACE, THIRD_PARTY_DOMAIN, EVENTS_ALLOW_PRIVATE_TARGETS), is a word, an address, a URL or a list rather than a key, so secret set shows it as it is typed and, from every source, trims it and checks it before anything is written, the way the Gateway reads it (PLAIN_SETTINGS in packages/cli/src/lib/secretValue.ts; the Gateway settings tables below say the same per name):

• EMAIL_PASSWORD_SIGN_IN, MCP_OAUTH_ENABLED, MCP_DCR_ENABLED: true or false, any case; 1, 0, on, off, yes and no are honoured too. The prompt says which one turns the feature off (false). HOSTED_OPEN_SIGNUP: true or false. BROWSER_APP_INSTALLS: on or off, in lowercase (the Gateway compares it as typed). EVENTS_ALLOW_PRIVATE_TARGETS: true or false, in lowercase (the Gateway turns it on for exactly true). CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN: everyone; to turn it off, pnpm everyapp secret unset CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN.
• EMAIL_FROM: an address, or Name <address> (parseEmailSender). EMAIL_PROVIDER: cloudflare or resend, any case.
• MASTODON_URL: an https origin with no path (oauthClientOrigin; a bare host is taken as https). MCP_ALLOWED_ORIGINS: http or https URLs, comma or space separated. CLOUDFLARE_ACCESS_OIDC_ISSUER: https://<team>.cloudflareaccess.com/cdn-cgi/access/sso/oidc/<client id>. CLOUDFLARE_ACCESS_TEAM_DOMAIN: <team>.cloudflareaccess.com, with or without https://. Both as the Gateway's accessUrl takes them: user info, a query or a fragment in the URL is refused.
• CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS: domains, comma or space separated (a leading @ is fine); THIRD_PARTY_DOMAIN: one domain, as the Gateway's thirdPartyDomain reads it (a trailing . is dropped; no @). CLOUDFLARE_ACCESS_AUD, CLOUDFLARE_ACCESS_APPS_AUD: AUD tags. AI_PROXY_EXTRA_ROUTES: /v1/... paths. A list with an entry of the wrong shape, or with none, is refused.
• MCP_AUDIT_RETENTION_DAYS: a whole number from 1 to 3650.
• EMAIL_FROM_NAME, CLOUDFLARE_ACCESS_OIDC_CLIENT_ID, CLOUDFLARE_ACCESS_OIDC_LABEL, DISPATCH_NAMESPACE: anything but nothing; the prompt still says what each is for.

At the prompt a refused answer is asked again with the reason. From --from-env or stdin it is SETTING_VALUE_INVALID: NAME can't be "<value>" (the value as typed, on one line, at most 64 characters) then the reason, with data.name and a fix saying what the setting takes (use true or false; false turns password sign-in off (only while Cloudflare Access sign-in is on)). Nothing is written. Under --json nothing else changes: there is still no prompt, and a value that passes is set as before.

A value never appears on cf's command line: patchWorkerSecrets writes a JSON merge patch ({ "secrets": { "NAME": { "name", "type": "secret_text", "text" } } }, null to remove) to a file in a private temp directory (mode 0600, removed afterwards; packages/cli/src/lib/cf/runner.ts) and passes --body @<file>. The first deploy's GATEWAY_URL and EVERY_APP_ORG_ID travel the same way, in cf deploy --secrets-file. Do not put a value in a chat message or a shell argument: export it and use --from-env.

secret unset

pnpm everyapp secret unset NAME… routes names as set does (an undeclared name still goes to the app). Before asking, it checks whether any target Worker holds any of the names; none does, and the result is done with NAME isn't set on the Gateway or <id>. Nothing changed. and data: { removed: false }. Otherwise it asks Remove NAME from the Gateway, and OTHER from <id>? (No by default). --yes (-y) skips the question; without a terminal (--json, CI) and without --yes it fails with CONFIRMATION_REQUIRED (Removing secrets needs confirmation, and there's no terminal to ask in), whose rerun adds --yes and is marked authorize: show it and ask before running it.

Under the leases, each target keeps only the names it holds (a merge patch of null for an absent name would make a version with no change); --verbose shows NAME isn't set on <worker> (progress secrets.held). The done message is Removed NAME from the Gateway, and OTHER from <id>, Live now. No deploy needed., with the same data shape as set. Unsetting a remote MCP credential also deletes its pin (progress secrets.pin: <NAME>'s pin to its MCP server's origin is gone).

secret list

pnpm everyapp secret list [<app>] prints names, never values. Flags: --gateway, --account-id, --json, --verbose. The optional <app> is an app id: the table for that app from any directory (its manifest from the registry); without it, the app in this directory, or outside one the Gateway's table and then every registered app's settings.

Outside an app's directory it lists the Gateway Worker's secrets as a NAME / SET BY table under Gateway secrets · <host>: every name that is not install-owned as you, each install-owned name present as setup, and of the settable names not set only those some registered app's manifest reads (hosted-only names only on a hosted install), the rest as one dim line, N more can be set. Then each registered app's settings table (below). Each remote MCP credential a live MCP app declares and the Gateway doesn't hold is listed among the unset names, and each MCP app that needs setup (its key or credential unset) gets a settings table of its own with the one secret set that sets it up; MCP apps that are ready are left out (pnpm everyapp mcp list shows them all). The done event's data is { gateway: { workerName: "every-app-gateway", names, settable, mcpCredentials }, apps: [{ id, setup }] } (names: the Worker's secrets, sorted; settable: SETTABLE_GATEWAY_SETTINGS; mcpCredentials: [{ name, apps, set }], each remote MCP credential name with the ids of the live apps that declare it and whether it is set; setup each app's AppSetup, below).

For one app (the app in this directory, or <app>) it is a SETTING / WHERE / STATUS table (settingsRows and renderSettingsTable in packages/cli/src/lib/app/settings.ts), one row per setting the manifest declares, in manifest order: the Gateway settings its providers and capabilities need (WHERE Gateway; an OAuth client's pair joined with +), then the app's own secrets (WHERE the app id), then each helper Worker's view of the app's own secrets (WHERE <helper> helper); reserved names (GATEWAY_URL, EVERY_APP_ORG_ID) only with --verbose.

• STATUS is the SETTINGS vocabulary status shares (settingStatus): ✓ set, ! not set (required, or every member of an unmet any-of group), not set (optional), not set (one of: <group>) when another member is set, ! not recorded for an app secret whose names the CLI never recorded, ! couldn't check when cf couldn't list a Worker. Before the first deploy the app's own rows read after first deploy, and the note <id> isn't deployed yet; its own secrets can be set after that. closes the output.
• Under the table, when something is unmet, each unmet setting as status describes it (describeUnmetSettings): <label>: <why> (the names when the manifest gives no why and the label doesn't name them), the provider's hint (what the key is and where it comes from, from its entry), Get it at <docs> when the registry or manifest knows where, and Guide: .claude/skills/everyapp/setup/<name>.md once per distinct guide; a provider registered on the Gateway has no guide file, and its line is Guide: pnpm everyapp provider show <id>. --json carries the same as each setting's hint and setup.
• No rows at all: <id> declares no secrets and needs no Gateway settings. (deployed or not).

Its data: { app: { id, deployed, workerName, declared, workers: [{ workerName, names, missing }], secretNames, settings, setup }, gateway: { workerName, names, needed: [{ name, required, set }], missing, settable }, next? }. secretNames is the app Worker's own names as cf listed them, reserved names dropped (null before the first deploy); settings is every setting with its state and setup the AppSetup summary (/docs/agent/json); needed[].required is true for a required setting or an any-of member. next mixes { command, note } objects and command strings: once deployed, pnpm everyapp configure <app> (setup.command.command) while something is unmet; before the first deploy, { command: "pnpm everyapp configure", note: "in the app's directory" } while something the Gateway holds is unmet, then pnpm everyapp deploy (alone when nothing is); absent for a deployed app that is ready, or an app with no rows.

Gateway settings

Every name pnpm everyapp secret set changes on the Gateway, from SETTABLE_GATEWAY_SETTINGS (packages/sdk/src/internal/gatewaySettings.ts) and the remote MCP credentials' _MCP_TOKEN family ("MCP apps" below), with what it configures (apps/every-app-gateway/src/env.d.ts and the modules named) and the manifest entry an app lists to use it. "Required" and "optional" are what the settings model reports for an app that lists the entry (appSettings() in packages/sdk/src/internal/appSettings.ts: required unless the entry says optional: true or names an anyOf group): required ones show as ! not set in secret list, optional ones as not set (optional).

Where a setting has a setup skill, its section names it as setup/<name>.md: that is packages/cli/skills/everyapp/setup/<name>.md in the EveryApp checkout and, in an app, .claude/skills/everyapp/setup/<name>.md (also under .agents/skills/everyapp/setup/; everyapp create copies the skill into both, packages/cli/src/lib/app/skill.ts); the index is setup/README.md. The skills hold the step-by-step setup of each integration; this page holds what each setting does.

AI providers

An app lists providers: ["openai"] and calls /api/ai/<provider>/... with createGatewayFetch(); ai.models and ai.routes in the manifest limit what it may ask for. Step by step: setup/openai.md, setup/openrouter.md, setup/workers-ai.md. The table is generated from the catalog's ai entries (/docs/agent/providers); a provider whose key (or, for Workers AI, the account) is unset answers ai_provider_not_configured.

One more AI setting is the Gateway's own: AI_PROXY_EXTRA_ROUTES, the OpenAI paths beyond inference apps may opt into (comma or space separated, each matching ^/v1(/[a-z0-9_-]+)+$, e.g. /v1/files; each covers its sub-paths). A path is allowed only when both this and the app's ai.routes list it (apps/every-app-gateway/src/server/ai-proxy.ts); the manifest entry is ai: { routes: [...] }, required when routes is non-empty.

API-key capabilities

An app lists capabilities: { <id>: { access: "read", why } } and calls the provider's real URLs with integrationFetch({ env, provider: "<id>", for }); the Gateway puts the key on the call and forwards it to the provider's hosts only. Step by step: setup/dataforseo.md, setup/context.md, and for every catalog provider setup/providers.md#<id>. The same DATAFORSEO_API_KEY also serves DataForSEO's tools straight to members' AI clients as an MCP app, with no page and nothing to deploy: pnpm everyapp mcp on dataforseo (/docs/agent/mcp). The table is generated from the catalog's api_key entries:

Registered providers

A provider the catalog doesn't have can be registered on one Gateway as a row of its providers table (pnpm everyapp provider add <spec>; /docs/agent/providers). Its settings are Gateway settings too, held on the Gateway Worker for every app, but they aren't in SETTABLE_GATEWAY_SETTINGS: the rows route them. Three rules hold for them:

• The prefix. Every setting a row names starts with its id upper-cased, - as _ (STRIPE_API_KEY for stripe), and is nobody else's: not one of the Gateway's own, not a catalog provider's, not another row's, not a name a registered app lists under secrets. provider add refuses anything else with PROVIDER_SECRET_TAKEN, and the Gateway skips such a row on every read.
• The routing. pnpm everyapp secret set STRIPE_API_KEY from any directory: the name isn't a catalog setting, so the command connects first, finds the row that holds it and sets it on the Gateway Worker. Before it asks for the value it prints STRIPE_API_KEY is Stripe's, registered by <who> on <date>; the key is sent to api.stripe.com.
• The binding. Once set, the row records what the key was set for (its hosts and auth); the Gateway reads the key only while the row still says the same. A row added and not yet given a key, or replaced (provider add --replace) since, reads as not set everywhere ("Needs setup", ! not set) and its calls answer integration_not_configured until secret set runs again. provider remove leaves the setting on the Gateway: secret unset removes it.

OAuth clients

One client per provider serves every organization on the Gateway, and two flows run on it (OAuth providers). The app-driven flow: the app lists capabilities: { <id>: { access: "write" } }, builds the authorize URL from integrationStatus()'s clientId, exchanges codes and refreshes tokens through integrationFetch() on the network's token endpoints (the Gateway puts the client on the request), keeps the user tokens and calls the network's API itself. The Gateway-owned flow (google-workspace, microsoft-365, slack, discord, and every OAuth provider added from a preset or a spec): the person connects once at /connect/<id> and the Gateway holds the tokens sealed; the app lists the provider with access: "read" (or write) and its scopes, and integrationFetch() reaches the provider's API hosts with the connected person's token put on by the Gateway. For that flow the client may also be pasted in Manage workspace → Providers instead of set here: the pasted copy is sealed in the oauth_clients table and is read only while the Worker setting of the same name is unset. A client with scope sets also names the sets the app uses, capabilities: { "google-workspace": { access: "write", scopes: ["gmail.read", "calendar.read"], why } } (google-workspace: identity, gmail.read, calendar.read, search-console.read, analytics.read; microsoft-365: identity, mail.read, calendar.read, all read-only; slack: channels.read, users.read, users.email, messages.write, channels.join, channels.manage, files.write, user-channels.manage), and the operator allows on the client's console the provider scopes behind the sets of every app they approve. The client secret never reaches an app. Both names of a pair are required. Step by step for the three with a skill: setup/google.md (the GOOGLE_WORKSPACE_* pair), setup/microsoft-365.md, setup/slack.md.

The developer consoles, redirect URIs, token endpoints and scopes of each client are in /docs/agent/repo/capabilities, generated from packages/sdk/src/internal/capabilities.ts. The Gateway-owned flow's redirect URI is https://<gateway>/connect/<id>/callback for every provider. An OAuth provider added as a row (pnpm everyapp provider add --oauth github-oauth) holds its client in the row's own family, <ID>_CLIENT_ID and <ID>_CLIENT_SECRET (GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET), routed by the rows as any registered provider's setting is and bound to the row's endpoints (oauth.client-bound-to-endpoints). X's OAuth 1.0a is not a capability: it signs every call with the user's token secret, so an app keeps X_API_KEY and X_API_SECRET as its own secrets; X's OAuth 2 is the x-oauth preset.

Email

The email service capability (sendEmail()), and the Gateway's own invitation and password-reset mail. The sender needs an address and a display name (parseEmailSender in packages/sdk/src/internal/email.ts): EMAIL_FROM is required; the name comes from EMAIL_FROM_NAME or, when that is unset, from EMAIL_FROM written as Name <address> (surrounding quotes are dropped), so EMAIL_FROM_NAME is required unless EMAIL_FROM carries the name. The Gateway can send once that sender parses and a provider is selectable: isEmailConfigured() in apps/every-app-gateway/src/server/email/sendEmail.ts is configuredSender() (the parse above) and selectEmailProvider() (chooseEmailProvider, below) both answering. Its own mail otherwise fails EMAIL_SENDER_NOT_CONFIGURED: Email sender is not configured. Set EMAIL_FROM and EMAIL_FROM_NAME, or use EMAIL_FROM="Name <email@example.com>". when EMAIL_FROM is set without a name, else Email sender is not configured. Set EMAIL_FROM and EMAIL_FROM_NAME. The capability registry lists EMAIL_FROM and EMAIL_FROM_NAME as the capability's settings and the four provider settings as optionalSettings (packages/sdk/src/internal/capabilities.ts), so the Gateway's setup dialog and secret list name both; secret list reads names, not values, so it calls EMAIL_FROM_NAME unset even when EMAIL_FROM carries the name. Whether the Gateway can send is isEmailConfigured(), above. Step by step: setup/email.md.

An app's own senders and inbound addresses are not Gateway settings: pnpm everyapp email set --sender … --inbound … in the app's directory, after its first deploy (/docs/agent/email).

MCP

Switches of the Gateway's /mcp and its OAuth authorization server (apps/every-app-gateway/src/server/oauth-flag.ts, mcp-auth/, toolbus/gateway-mcp.ts). No app lists anything for these.

MCP apps

An MCP app's key or credential is a Gateway setting like any other (/docs/agent/mcp). The built-in DataForSEO app reads DATAFORSEO_API_KEY (API-key capabilities, above; step by step setup/dataforseo.md). A remote MCP app, any MCP server added with pnpm everyapp mcp add <url>, reads one setting its registry row names, in a family of its own:

• The family. mcp add names the credential <ID>_MCP_TOKEN, the app id upper-cased with - as _ (remoteMcpSecretName); --secret <NAME> picks another name ending in _MCP_TOKEN, and nothing else. Because the family is a fixed rule, secret set sends such a name to the Gateway without reading the registry, an app's own secret can't take one (below), and an owner or admin adding a server from Admin → Apps can't point a key the Gateway already holds (OPENAI_API_KEY) at their own URL. The settings model reads the row's credential as one required Gateway setting (kind remote-mcp, setup guide setup/remote-mcp.md); a server added with --auth none needs nothing.
• Setting it. pnpm everyapp secret set TREG_MCP_TOKEN, or mcp add itself: at a terminal it asks Set TREG_MCP_TOKEN now? and reads the value with the hidden prompt; mcp add --from-env VAR reads it from the environment. Never from the Gateway's UI, never over MCP. The value goes where every Gateway setting goes, and nowhere else: never to an AI client, an audit row, a log line, an error or a tool result.
• The pin. A credential is pinned to one origin. After setting the value, secret set writes (name, origin, bound_by, bound_at) to remote_mcp_credentials in the Gateway's D1 (migration 0011), the origin being that of the live MCP app that declares the name; setting it again re-pins it to that app's origin. The Gateway sends a credential only to the origin it is pinned to, so an owner or admin who re-points a row, or removes one and adds another under the same id, can't move it: such a row needs setup until the operator runs secret set again. A credential set some other way (the Cloudflare dashboard) has no pin and is sent nowhere: every row naming it reads as needing setup (mcp.remote.credential_unpinned) until the operator runs secret set, which pins it; the Gateway never pins on first use (since 2026-10-25; before, the first row to use a name took it). The pin failing to write after the value is set is said (progress secrets.pin), not raised: the value is live but unpinned, so run secret set again.
• Warnings. REMOTE_MCP_SECRET_UNDECLARED: no live MCP app declares the name; it keeps an earlier pin, if it had one, else the Gateway pins it to the first app that uses it. REMOTE_MCP_SECRET_AMBIGUOUS: live MCP apps at more than one origin declare it (only a row edited by hand can: mcp add refuses a second origin with REMOTE_MCP_SECRET_TAKEN), so it is pinned to none and sent to none until one is removed. (/docs/agent/errors)
• Unset. pnpm everyapp secret unset TREG_MCP_TOKEN removes the value and its pin. mcp remove removes the app and leaves both.
• Listing. secret list names each remote credential a live MCP app declares and doesn't have yet among the Gateway's unset names, lists each MCP app that needs setup with its secret set, and carries every credential in data.gateway.mcpCredentials. pnpm everyapp mcp show <id> says whether the credential is set and which origin it is pinned to.

Cloudflare Access and sign-in

Read by apps/every-app-gateway/src/auth/cloudflare-access/config.ts on a self-hosted Gateway only; a hosted Gateway ignores them and EMAIL_PASSWORD_SIGN_IN (its platformPolicy has no Access sign-in; the log says so once, apps/every-app-gateway/src/auth/cloudflare-access/index.ts). Operator-only; see /docs/agent/access and docs/runbooks/cloudflare-access.md. Step by step: setup/access.md.

Three of them the operator does not set by hand: everyapp access on (packages/cli/src/commands/access/index.ts) writes ACCESS_SETTINGS from packages/cli/src/lib/access/settings.ts, CLOUDFLARE_ACCESS_TEAM_DOMAIN, CLOUDFLARE_ACCESS_APPS_AUD and CLOUDFLARE_ACCESS_AUD, in one new version of the Gateway Worker after it has created or updated the two Access applications, through applyGatewaySettings in packages/cli/src/commands/secret/index.ts: the same gateway.secrets lease, replaceable-version check, cf workers secrets bulk call and version record as secret set. Values can't be read back from a Worker, so it records what it wrote (team domain and both AUD tags) in the Gateway's D1, table _everyapp_access (packages/cli/src/lib/access/record.ts), and writes the three again only when one is missing on the Worker, when it created an application, when there is no record or the record doesn't name the current team and applications (an application recreated in the dashboard has a new AUD tag, and the old one locks everyone out), or with --write-settings; otherwise it reports Gateway settings kept: they name these applications already (--write-settings writes them again). everyapp access off removes whichever of the three the Worker holds, in one version, so passwords sign people in again at once, then clears the record. everyapp status reports Access as on when all three are on the Worker (data.access: { on, teamDomain }, accessStateOf in packages/cli/src/lib/access/settings.ts). On a hosted Gateway access on fails ACCESS_HOSTED (This Gateway can't be put behind Cloudflare Access). The rest of the table stays secret set: access on ends by naming pnpm everyapp secret set CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS (when run with --email-domain) and pnpm everyapp secret set EMAIL_PASSWORD_SIGN_IN (false, once everyone has signed in through Access) as next steps.

Sign-in providers

"Continue with Google" (Microsoft, GitHub, Apple, Cloudflare, or any OpenID Connect issuer) beside passwords, on self-hosted and hosted Gateways alike. The catalog is packages/sdk/src/internal/signInProviders.ts (SIGN_IN_PROVIDERS); the Gateway reads the settings in apps/every-app-gateway/src/auth/sign-in-providers/config.ts. The person's page is Sign in with Google and others; every command, flag, code and rule is Sign-in providers, and the operator's runbook docs/runbooks/sign-in-providers.md. Step by step: setup/signin-google.md, setup/signin-microsoft.md, setup/signin-github.md, setup/signin-apple.md, setup/signin-cloudflare.md, setup/signin-oidc.md.

Every name is <ID>_SIGNIN_<FIELD>, FIELD one of CLIENT_ID, CLIENT_SECRET, ISSUER, LABEL or TENANT (SIGN_IN_SETTING_PATTERN, isSignInSettingName). The _SIGNIN_ infix keeps the family apart from the OAuth clients the Gateway holds for apps (GOOGLE_WORKSPACE_CLIENT_ID, above), the API-key providers' <ID>_API_KEY and the MCP apps' <ID>_MCP_TOKEN: a registered provider row can't take a name in the family (PROVIDER_SECRET_TAKEN, rowSecretProblem), nor can an app's manifest (secrets refuses it: "is a sign-in provider's setting name"). The values are Worker secrets, set with pnpm everyapp signin add <id> (which asks for each one, hidden for the client secret, and prints the redirect URL to register with the provider; unattended --client-id, --client-secret-from-env <VAR>, --issuer and --label for oidc, --tenant for microsoft; the whole family in one Gateway version, a setting set already and not given kept) or pnpm everyapp secret set <NAME> (which checks the issuer, the tenant and the label as the Gateway reads them, and refuses a name of the family no provider reads); pnpm everyapp signin list and signin show <id> say what is set, signin remove <id> unsets the family; never from the Gateway's UI, never over MCP (a stolen session or token can't add a way in). A provider is on only when every required setting is set; with some set and some missing it is off, the log says what is missing (signin.config_problem, once per isolate) and Manage workspace → Sign-in shows it as needing setup. The redirect URL to register is https://<gateway>/api/auth/callback/<id> (signInCallbackUrl).

Deployers and the hosted tier

Events out

The event bus's one switch (/docs/agent/events); no app lists anything for it.

Install-owned settings: never set by hand

INSTALL_OWNED_GATEWAY_SETTINGS: GATEWAY_URL, APP_BASE_DOMAIN, BETTER_AUTH_SECRET, JWT_PRIVATE_KEY, JWT_PUBLIC_KEY, GATEWAY_DEPLOYMENT_MODE, CLOUDFLARE_ACCOUNT_ID, THIRD_PARTY_DEPLOYS. secret set refuses them outside an app's directory (SECRET_NOT_SETTABLE); in an app's directory they are app names like any other: SECRET_NOT_DECLARED unless the manifest lists them, in which case they go to the app (notRoutable in packages/cli/src/commands/secret/index.ts). secret list shows the ones present on the Gateway as setup.

• The Gateway's first upload generates and sends GATEWAY_URL, BETTER_AUTH_SECRET (32 random bytes, base64), JWT_PRIVATE_KEY and JWT_PUBLIC_KEY (RS256, 2048-bit, PKCS#8 and SPKI PEM), GATEWAY_DEPLOYMENT_MODE (self_hosted on a Worker's first upload; hosted is the only other value apps/every-app-gateway/src/server/platform-policy.ts accepts, the hosted Gateway this page refers to, and no command sets it any more; anything else, unset included, is invalid and turns every capability off; a mode the install row already records is kept, so it is fixed for the Gateway's life: packages/cli/src/lib/gateway/apply.ts) and CLOUDFLARE_ACCOUNT_ID with cf deploy --secrets-file (packages/cli/src/lib/gateway/secretsFile.ts). APP_BASE_DOMAIN is a text binding the deploy patches into the Gateway's Build Output (packages/cli/src/lib/gateway/patchBuildOutput.ts).
• THIRD_PARTY_DEPLOYS is the hosted launch gate: exactly on opens the third-party deploy API. The CLI never sets it: set it by hand on the every-app-gateway Worker's secrets once the launch checks pass, and delete it to close the API again (deployed apps keep running; nobody can deploy) (docs/runbooks/hosted-install.md, /docs/agent/repo/runbooks/hosted-install).
• An app's own Worker may hold a secret of the same name (OpenSEO's BETTER_AUTH_SECRET): list it under the app's secrets and set it from the app's directory; the two never meet.
• Rotating the identity pair is docs/runbooks/key-rotation.md (/docs/agent/repo/runbooks/key-rotation): generate the pair with node apps/every-app-gateway/regenerate-secrets.js (a PKCS#8 private key and an SPKI public key, RS256, 2048-bit; an OpenSSH public key or a PKCS#1 BEGIN RSA PRIVATE KEY private key deploys without error and fails at runtime), replace JWT_PRIVATE_KEY and JWT_PUBLIC_KEY together in the Cloudflare dashboard (never one half), write the new public key into the install row (_everyapp_install.jwt_public_key, where app deploys read it), run pnpm everyapp setup --redeploy in a terminal, then pnpm everyapp deploy from every app's directory, since each app carries the public key in EVERYAPP_IDENTITY_PUBLIC_KEYS. Until every app is redeployed, apps with the old key answer 401 to new identities: the SDK tries each key in EVERYAPP_IDENTITY_PUBLIC_KEYS and throws IdentityError (status 401, identity verification failed: …, packages/sdk/src/internal/identity.ts), which the app's handler answers as { "error": "unauthenticated" } (packages/sdk/src/server/everyApp.ts). A deploy that stops with IDENTITY_KEY_UNKNOWN is reading an install row with no public key (a Gateway first deployed by an older CLI): do the install-row step with the Gateway's current JWT_PUBLIC_KEY. Every other key (a provider's, a client's, an app's own) rotates with pnpm everyapp secret set NAME again: one new Worker version, live at once.

Dev-only settings

DEV_ONLY_GATEWAY_SETTINGS: MCP_ACCESS_TOKEN_TTL and DATAFORSEO_SANDBOX. Set in the Gateway's own .dev.vars, never deployed, honored only when GATEWAY_URL starts with http://; secret set refuses them (SECRET_NOT_SETTABLE). MCP_ACCESS_TOKEN_TTL: shorter OAuth access tokens in seconds (clamped to 60 through 3600, the normal lifetime; apps/every-app-gateway/src/server/mcp-auth/config.ts). DATAFORSEO_SANDBOX: true sends the DataForSEO MCP app's tool calls (/docs/agent/mcp#mcp-apps "MCP apps") to sandbox.dataforseo.com, which answers like production with made-up data at no charge, still with the DATAFORSEO_API_KEY from the same file (apps/every-app-gateway/src/server/provider-apps/dataforseo.ts).

Reserved names an app secret cannot take

Checked without regard to case, in the CLI (assertAppSecretName, packages/cli/src/lib/app/secrets.ts), the manifest validator and everyAppWorker():

Nor can an app's secret end in _MCP_TOKEN, in any case: the family belongs to the Gateway's remote MCP credentials ("MCP apps" above). The strict manifest validator refuses it (<NAME> is a remote MCP app's credential name (every name ending in _MCP_TOKEN is the Gateway's, set with `everyapp secret set`); give the app's secret another name, packages/perimeter/src/manifest/manifest.ts), and secret set sends a name in the family to the Gateway from any directory, so it never reaches an app's Worker.

The SDK keeps the same rule as a regex in packages/sdk/src/cloudflare/worker.ts (^(GATEWAY_URL|CF_VERSION_METADATA|EVERYAPP_\w*|EVERY_APP_\w*|APP__\w*)$, case-insensitive): a manifest listing one fails the Worker definition with secrets: NAME is a name the deploy sets or a binding it builds.

App secrets

Declaring them

In everyapp.config.ts:

export default {
  id: "todo",
  secrets: ["GITHUB_TOKEN", "STRIPE_KEY"],
} as const;

A name may also be an object: { name: "GITHUB_TOKEN", why, docs, optional: true } or anyOf: "<group>", and setup: "setup/<name>.md" for its guide in the everyapp skill. A bare name is required: the app shows Needs setup and doesn't open until it is set (pnpm everyapp configure <app> asks for it); optional: true lets it open without; one member of an any-of group is enough. Rules and messages: /docs/agent/manifest.

AppSecretsSchemaStrict in packages/perimeter/src/manifest/manifest.ts checks the list when the CLI parses the manifest (validateManifestStrict; errors read Invalid everyapp.config: secrets.<index>: …):

Install-owned Gateway names are not refused here: an app may list BETTER_AUTH_SECRET as its own.

Setting and reading them

1. Deploy the app once (pnpm everyapp deploy): the production build declares no app secret, and the upload carries only GATEWAY_URL and EVERY_APP_ORG_ID.
2. pnpm everyapp configure todo asks for each, from anywhere (pnpm everyapp configure todo --from-env --json for an agent). One name at a time, from the app's directory: pnpm everyapp secret set GITHUB_TOKEN (a person at the prompt) or pnpm everyapp secret set GITHUB_TOKEN --from-env GITHUB_TOKEN --json (an agent). The value lands on the app's Worker and on every helper Worker in one new version each; later deploys keep it: the production build declares no app secret (packages/sdk/src/cloudflare/worker.ts, the secrets field), and cf deploy (the CLI's pinned cf, 1.0.0-beta.14) uploads every version with keepSecrets on, which puts secret_text and secret_key in the upload's keep_bindings, so a secret absent from the Build Output and the --secrets-file stays on the Worker.
3. In the Worker, env.GITHUB_TOKEN is the string. Type it as optional, since it is absent in development until set locally, by adding to the app's src/env.d.ts:

declare namespace Cloudflare {
  interface Env {
    GITHUB_TOKEN?: string;
    STRIPE_KEY?: string;
  }
}

(the shape packages/sdk/src/env.d.ts and apps/every-app-gateway/src/env.d.ts use; cf generates the bindings' own types from cloudflare.config.ts).

4. pnpm everyapp secret unset GITHUB_TOKEN removes it from every Worker that holds it. Dropping the name from the manifest does not remove the value: unset still accepts the dropped name.

A secret's value is never read back by the CLI: secret list and the Gateway's Admin → Apps (where a shared app's manifest, its secrets names included, is visible to every organization's admins) show names only.

In development

everyapp dev runs the app with cf dev and no Gateway binding. everyAppWorker() (packages/sdk/src/cloudflare/worker.ts, addSecrets) declares as a secret binding each of these names that is set locally, so the Vite plugin passes the value through:

• every name under the manifest's secrets;
• the Gateway settings of the manifest's providers and capabilities (DEV_GATEWAY_KEYS: OPENAI_API_KEY, OPENROUTER_API_KEY, WORKERS_AI_API_TOKEN with CLOUDFLARE_ACCOUNT_ID, DATAFORSEO_API_KEY, CONTEXT_API_KEY, each OAuth client's id and secret and MASTODON_URL, email's EMAIL_FROM, EMAIL_FROM_NAME, EMAIL_REST_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, RESEND_API_KEY, EMAIL_PROVIDER), under the same names the Gateway uses;
• EVERYAPP_EMAIL_SENDERS when the manifest lists email (the senders standing in for everyapp email set --sender).

"Set locally" is read as the Vite plugin reads secrets (localEnv): when .dev.vars.<mode> or .dev.vars exists in the app root, that file alone; otherwise .env, .env.local, .env.<mode>, .env.<mode>.local and the process environment, later ones winning. A name that is not set is not declared, so env.NAME is undefined. everyapp dev never writes .dev.vars; keep it out of git.

The SDK's direct fallback then uses those values in place of the Gateway, only with EVERYAPP_DEV set (which everyAppWorker() sets in development):

• createGatewayFetch({ env }) (packages/sdk/src/server/gatewayFetch.ts): with no binding and no provider fully set, it throws ConfigurationError: AI gateway unavailable: deploy with the EVERY_APP_GATEWAY binding, or set the provider's key (OPENAI_API_KEY, OPENROUTER_API_KEY or WORKERS_AI_API_TOKEN with CLOUDFLARE_ACCOUNT_ID) in .dev.vars for direct local development. A call to a provider that is not set throws Set OPENAI_API_KEY in .dev.vars to call openai in local development. Otherwise the call goes to the provider's origin with Authorization: Bearer <key>; Workers AI's path is joined under /client/v4/accounts/<id>/ai and its stream normalized as the Gateway does. Only /api/ai/openai, /api/ai/openrouter and /api/ai/workers-ai paths are accepted.
• integrationFetch({ env, provider }) (packages/sdk/src/server/integrationFetch.ts): with no binding and no local credentials it throws <Label> is unavailable: deploy with the EVERY_APP_GATEWAY binding, or set <SETTINGS> in .dev.vars for local development. (e.g. DataForSEO is unavailable: … set DATAFORSEO_API_KEY …; an OAuth client names its id, secret and host setting). Otherwise the call goes straight to the provider with the developer's key, or to the network's token endpoint with the developer's client injected by the Gateway's own rule; an API host or path outside the capability's is a TypeError. Naming a service (email, members) throws <id> is a gateway service: call its helper from @every-app/sdk/server (sendEmail(), listMembers()), not integrationFetch().
• integrationStatus({ env, provider }) in dev answers requested: true and configured/ready true when EVERYAPP_DEV and the key are set (an OAuth client: its id and secret; email: EMAIL_FROM; members: EVERYAPP_DEV alone).

Deployed, none of this applies: the binding exists, the fallback is never taken, and provider keys set as an app's own secrets are refused by the manifest validator.

An app secret or a Secrets Store secret

An app secret (secrets, set with everyapp configure <app> or secret set) is a value on the app's own Workers, read as the string env.NAME; it is the default for a key only this app uses. A Cloudflare Secrets Store secret (resources.secretsStore: [{ name: "NAME" }], /docs/agent/manifest, "Secrets Store") lives once in the account's store, where the dashboard manages, rotates and audits it, and the Worker fetches it with await env.NAME.get(): the first deploy creates it as <worker>--<binding> from NAME in .everyapp/secrets.env (the store must exist: SECRETS_STORE_MISSING), and later deploys never rewrite it, so its value changes in the dashboard, not with secret set. One name is one or the other: the manifest refuses a secrets name that is also a binding.

Capabilities, providers or your own secret

A capability entry takes access (a level the capability offers; write on an api_key capability or read on an OAuth client is refused at deploy) and an optional why (at most 200 characters). An unknown id is refused: unknown capability (the gateway offers: dataforseo, context, email, members, linkedin, …).

Attribution. Every brokered call says whom it is for (packages/sdk/src/server/attribution.ts): for: request attributes it to the request's user by the identity the Gateway put on it; for: { background: true, organizationId } to an organization for work no request started (crons, Workflows, queues, an email() handler). An organization's own app may omit for for background work (the call is the app's); a shared app's Worker (EVERYAPP_SHARED) must pass one or the other or the SDK throws AttributionError (code attribution_required) before any call. The organization travels as x-everyapp-org. Every attributed provider and AI call is counted per organization, app, member and provider (usage_daily, usage_monthly) and shown under Manage workspace → Usage, where an owner or admin may cap an app's provider calls per UTC month (org_app_settings.monthly_call_cap), set one default cap for every app without a cap of its own (org_settings.default_monthly_call_cap) and leave one app out of the default (org_app_settings.unlimited); every cap is off by default, and the app's own cap wins over the default. Past the effective cap the Gateway answers 429 app_monthly_cap_exceeded and counts nothing (the message names the cap, the workspace default when that is what binds, and the role that raises it, never a person); the app still opens, and its Usage row and its card say Paused. An org_app_settings row holds exactly one of (monthly_call_cap set, unlimited false) or (monthly_call_cap null, unlimited true), both columns written in one statement; the reader lets a cap win. With a cap set, checkMonthlyCap (apps/every-app-gateway/src/server/app-cap.ts) answers { exceeded, cap, calls, month, source } on every check, and that standing goes to the event bus after the answer (cap.warning at 80%, cap.reached and app.paused_cap at the cap; /docs/agent/events), where the built-in Cap alerts mail owners and admins at 80% and at the cap once the Gateway can send mail (Manage workspace → Events). The Gateway's own services (email, members) are neither counted nor capped.

Status. integrationStatus({ env, provider }) answers { requested, configured, ready } (over the binding, GET /api/integrations/<id>, without calling the provider): requested is whether the deployed manifest lists the capability, configured whether the Gateway holds its settings, ready whether calls would go through. configured is false for an app that doesn't list the capability, so no app learns what the operator holds (api_key: apps/every-app-gateway/src/server/integration-proxy.ts; oauth_client: capabilities/oauthClient.ts; email: capabilities/email.ts). members, which holds nothing, answers configured: true whether or not the app lists it and lets only ready follow requested (capabilities/members.ts). email adds sender, senders and provider (cloudflare or resend); an OAuth client adds clientId and, for Mastodon, origin, only once the Gateway holds the client; a client with scope sets (google-workspace, microsoft-365, slack) adds scopeSets (the manifest's names) and scopes (the provider strings for the authorize URL, which authorizeUrl() builds: /docs/agent/identity). Show "an admin needs to set up X" from ready instead of failing mid-task.

Refusals. A refusal the Gateway makes itself carries its code in the x-everyapp-error header; gatewayRefusal(response) returns { status, code, message } or null for the provider's own answer, and sendEmail()/listMembers() throw GatewayRefusalError with the same fields. The codes an app sees for configuration and for the shape of an AI or token call (apps/every-app-gateway/src/server/ai-proxy.ts, integration-proxy.ts, capabilities/oauthClient.ts):

members_list_failed, caller_not_registered and invalid_gateway_route are on /docs/agent/identity; the email_* codes on /docs/agent/email. The full check order per kind, the email message rules and codes, and the OAuth clients' tables are in /docs/agent/repo/capabilities (docs/capabilities.md).

The Postgres secrets file

.everyapp/secrets.env in the app root (packages/cli/src/lib/app/deploySecrets.ts) holds what everyapp deploy itself needs to reach the app's Postgres database, in dotenv syntax. The deploy reads it only when the manifest has migrations.dialect: "postgresql", resources.hyperdrive or resources.secretsStore, adds .everyapp/ to the app's .gitignore when it reads it, and never uploads, prints or records a value from it (output that would echo one is redacted). Unlike the app's own secrets, nothing in it reaches the Worker as a value: it binds the Hyperdrive config, which holds the origin's credentials in Cloudflare, and the Secrets Store secret, which holds its value in the account's store. The file also holds the value each new resources.secretsStore secret is created with, under the binding's own name (STRIPE_KEY=…): read only to create a secret that isn't in the store yet, sent to cf in a private body file, and never rewritten on a later deploy; missing when it is needed: SECRETS_STORE_VALUE_MISSING.

Each value is postgres://user:password@host:5432/database (postgres, postgresql or mysql; the port defaults to 5432 or 3306). A value that isn't a URL, isn't one of those schemes, or lacks a host, database, user or password is DATABASE_URL_INVALID, whose message names the variable and never the value. Every origin is checked before any config is created. A Hyperdrive config not recorded as the app's is adopted only when it connects to the origin in this file, so binding it gives the app no database it couldn't already reach; a recorded one whose host, port, database or user differ is pointed at the origin (packages/cli/src/lib/app/resources.ts). In development, a local Postgres URL goes in .dev.vars or .env as CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>. The person writes this file; everyapp configure sets what the Gateway and the app's Worker hold and doesn't write it. Which databases, which URL (Neon's and Supabase's direct one), the code, and Turso (an app secret, not this file): Postgres.

Hosted third-party apps

An app on the dispatch tier (a third-party app the Gateway's own deploy API or a browser install deploys, apps/every-app-gateway/src/server/deploy/) cannot have secrets of its own yet. Both go through parseManifest in run.ts (routes.ts for the deploy API, install.ts for the browser install), which refuses the manifest (manifestProblems in apps/every-app-gateway/src/server/deploy/metadata.ts) as BUNDLE_REFUSED, 422: The app can't be deployed as a third-party app: then it declares secrets, which third-party apps can't have yet; a Build Output with any secret binding besides GATEWAY_URL and EVERY_APP_ORG_ID is refused the same way (bundleProblems: <name> is a secret; third-party apps can't have secrets of their own yet). manifestTierProblems (packages/perimeter/src/manifest/manifest.ts: secrets: third-party apps can't have secrets of their own yet) is the same rule in pnpm everyapp deploy (packages/cli/src/commands/deploy/deployApp.ts), TIER_POLICY (<id> can't be deployed as configured then each problem; fix: change everyapp.config.ts, then deploy again), for an app the registry already records on the dispatch tier. Such an app reaches keys only through providers and capabilities. The deploy API's bearer is a deploy key: a personal access token with the deploy scope and nothing else (* doesn't count), of a live owner or admin of the organization it is bound to, checked on every request and minted in the Gateway's Admin → Tokens as Deploy key (apps/every-app-gateway/src/server/deploy/auth.ts; DEPLOY_SCOPE in apps/every-app-gateway/src/server/user-pat-scopes.ts). The Gateway keeps its hash (hashUserPat, apps/every-app-gateway/src/server/services/UserPatService.ts) and the caller keeps the value, so it is in none of the three places above and never a secret on any Worker.

Security notes

From docs/security-model.md (/docs/agent/repo/security-model):

• Secret values reach cf only in private temp files (0600, removed afterwards) or the environment, never argv or output; .everyapp/secrets.env values never reach a Worker.
• secret set|unset change the live Worker without a deploy; they take the Cloudflare login's authority and do not yet check the platform-admin rule of the hosted Gateway.
• The Gateway's logs redact cookie, authorization, set-cookie and any token, secret, password or code field; capability logs name hosts, paths and status, never bodies or keys.
• Cloudflare Access settings are Worker secrets only, never the admin UI (everyapp access on|off writes them as Worker secrets too). CF_DEPLOY_TOKEN on a hosted Gateway lets whoever reads the Gateway's secrets deploy into the namespace.

The boundaries these rules follow (which Worker holds which key, what reaches an app's Worker, what only the Gateway brokers) are in docs/threat-model.md (/docs/agent/repo/threat-model).

Sources

• packages/sdk/src/internal/gatewaySettings.ts
• packages/sdk/src/internal/remoteMcp.ts
• packages/sdk/src/internal/appSettings.ts
• packages/sdk/src/internal/aiProviders.ts
• packages/sdk/src/internal/capabilities.ts
• packages/sdk/src/internal/email.ts
• packages/sdk/src/internal/identity.ts
• packages/sdk/src/internal/protocol.ts
• packages/sdk/src/internal/oauthClient.ts
• packages/sdk/README.md
• packages/sdk/src/cloudflare/worker.ts
• packages/sdk/src/server/gatewayFetch.ts
• packages/sdk/src/server/integrationFetch.ts
• packages/sdk/src/server/attribution.ts
• packages/sdk/src/server/everyApp.ts
• packages/sdk/src/env.d.ts
• packages/cli/src/commands/configure/command.ts
• packages/cli/src/commands/configure/index.ts
• packages/cli/src/commands/secret/command.ts
• packages/cli/src/commands/secret/index.ts
• packages/cli/src/lib/app/settings.ts
• packages/cli/src/commands/access/command.ts
• packages/cli/src/commands/access/index.ts
• packages/cli/src/lib/access/settings.ts
• packages/cli/src/lib/access/record.ts
• packages/cli/src/lib/app/skill.ts
• packages/cli/skills/everyapp/SKILL.md
• packages/cli/src/lib/output/time.ts
• packages/cli/src/commands/flags.ts
• packages/cli/src/commands/setup/runSetup.ts
• packages/cli/src/commands/deploy/index.ts
• packages/cli/src/commands/deploy/deployApp.ts
• packages/cli/src/lib/gateway/apply.ts
• packages/cli/src/lib/migrations/localCli.ts
• packages/cli/src/lib/migrations/postgres.ts
• packages/cli/src/lib/migrations/prisma.ts
• packages/cli/src/lib/app/secrets.ts
• packages/cli/src/lib/app/deploySecrets.ts
• packages/cli/src/lib/app/resources.ts
• packages/cli/src/lib/secretValue.ts
• packages/cli/src/lib/cf/secrets.ts
• packages/cli/src/lib/cf/deploy.ts
• packages/cli/src/lib/cf/runner.ts
• packages/cli/src/lib/gateway/secretsFile.ts
• packages/cli/src/lib/gateway/lease.ts
• packages/cli/src/lib/gateway/remoteMcpApps.ts
• packages/cli/src/lib/output/prompt.ts
• packages/cli/src/lib/output/events.ts
• packages/cli/src/lib/errors.ts
• packages/perimeter/src/manifest/manifest.ts
• apps/every-app-gateway/src/env.d.ts
• apps/every-app-gateway/src/db/remote-mcp.schema.ts
• apps/every-app-gateway/cloudflare.config.ts
• apps/every-app-gateway/src/optional-secrets.test.ts
• apps/every-app-gateway/src/server/oauth-flag.ts
• apps/every-app-gateway/src/server/mcp-auth/config.ts
• apps/every-app-gateway/src/server/mcp-auth/maintenance.ts
• apps/every-app-gateway/src/server/toolbus/gateway-mcp.ts
• apps/every-app-gateway/src/server/ai-proxy.ts
• apps/every-app-gateway/src/server/platform-policy.ts
• apps/every-app-gateway/src/server/deploy/browser-install.ts
• apps/every-app-gateway/src/server/deploy/cfRestDeployer.ts
• apps/every-app-gateway/src/server/deploy/metadata.ts
• apps/every-app-gateway/src/server/deploy/run.ts
• apps/every-app-gateway/src/server/deploy/errors.ts
• apps/every-app-gateway/src/server/deploy/auth.ts
• apps/every-app-gateway/src/server/user-pat-scopes.ts
• apps/every-app-gateway/src/server/services/UserPatService.ts
• apps/every-app-gateway/src/server/app-gateway-entrypoint.ts
• apps/every-app-gateway/src/server/integration-proxy.ts
• apps/every-app-gateway/src/server/capabilities/members.ts
• apps/every-app-gateway/src/server/capabilities/oauthClient.ts
• apps/every-app-gateway/src/server/capabilities/email.ts
• apps/every-app-gateway/src/server/email/sendEmail.ts
• apps/every-app-gateway/src/auth/cloudflare-access/config.ts
• apps/every-app-gateway/src/auth/cloudflare-access/index.ts
• docs/capabilities.md
• docs/runbooks/key-rotation.md
• docs/runbooks/browser-app-install.md
• docs/runbooks/hosted-install.md
• docs/security-model.md