Secrets

A secret is a value an agent may use and must never see written down. It is stored in the platform’s vault, named in an agent’s secrets: list, and handed to that agent’s scripts as an environment variable at run time. It is never written into the workspace, never printed into a prompt, and never in git — which is what makes a workspace safe to commit.

Setting one

foldrun secrets set STRIPE_KEY               # this workspace's; prompted, never echoed
foldrun secrets set STRIPE_KEY --account     # the account's, shared by every workspace
foldrun secrets ls

Or in the dashboard under Settings → Secrets, or over the API:

PUT /api/secrets   { "name": "STRIPE_KEY", "value": "sk_live_…" }

PUT takes a name plus exactly one shape:

Reads return which secrets exist, never their values.

Scopes

A secret lives at the account or in one workspace. An agent looks in its workspace first, then the account; a workspace secret shadows an account one of the same name. The run trace says which scope each secret came from (secret DATAFORSEO_LOGIN ← workspace scope), so a workspace quietly falling back to a shared credential is visible rather than silent.

Put a credential at the account when every workspace should use the same one — your model provider, your email sender. Put it in a workspace when it is that job’s — a customer’s Search Console, a CRM key.

How an agent gets it

---
name: enricher
tools: [crm_lookup]
secrets: [OI_CRM_API_KEY]
---

The agent’s scripts see OI_CRM_API_KEY in their environment and nothing else. The model never sees the value: it sees that a tool exists, calls it, and the script reads the variable. The assembled prompt names which secrets are available and says, in as many words, never to print or write them.

A verify: command on a step runs with the same environment, so a check can call the same API the step did.

Connected accounts

Some third parties are connected rather than pasted — Google, GitHub, anything OAuth. Settings → Connections walks the consent flow once and stores the result as an oauth2 secret; the platform refreshes it. An agent names it in secrets: like any other.

How they are kept

Every account has its own encryption key. Secrets are sealed under it, and the account keys are wrapped by one root key the platform holds. A stolen copy of one account’s secrets file opens nothing without the root key, and the root key is not in any backup — the sealed backup of the platform’s own configuration is encrypted to a key the platform does not hold. See Security and, for a self-hosted install, Self-hosting.

Rotating a secret is setting it again. The next run reads the new value; runs in flight keep the one they started with.