Skip to content

Docs

Environment variables

Tofu keeps each variable’s name, scopes and whether it is a secret. A secret’s value goes straight to the hosting provider’s write-only store, and nothing in Tofu — the dashboard, your agent or its database — can read it back.

Agent tools

  • listEnv
  • setPublicEnv
  • deletePublicEnv
  • manageEnvironment

Where a value lives

KindWhat Tofu keeps
SecretThe name, its scopes and a masked preview (the last four characters; a value of four or fewer is masked entirely). The value is sent to the hosting provider as sensitive and never comes back, so a secret is saved only with the production scope: the provider is the only place it is kept.
Not a secretThe name, its scopes and the value, which the dashboard shows.
ManagedWritten by Tofu — the database connection, for example — and read-only: see Database.

Every variable carries one or more scopes — production, preview and development — and a new one gets production and preview unless you choose otherwise. Tofu puts every version of your app online at its address, so every version it builds reads the production variables and no others. A variable that is not a secret can be kept without production, and no version Tofu builds reads it; a secret cannot, because Tofu never keeps its value itself.

Adding variables

On the app’s Keys & settings page in the dashboard — and, for a public value, by a coding agent on your computer.

  1. Before the first deployment

    Variables that are not secrets can be saved already; a secret needs the app's hosting project, which the first deployment creates.

  2. Before every build

    Each deployment receives the production variables before the build starts, so a build step can read them.

  3. On the next deployment

    A change applies to deployments that follow it. Saving does not redeploy the app.

A secret stays a secret: it cannot be turned into a plain variable later. Delete it and add it again if it was never meant to be one.

Importing a .env file

Pasting a .env file treats every value as a secret, because a variable's name cannot prove its value holds no credential — a DATABASE_URL with a password in it, for example. To store public configuration before deploying, add it on its own with Secret unchecked.

Lines that are invalid, that name a reserved key or that name a managed variable are skipped. An import saves one variable at a time, so if something fails partway, the ones before it are saved and the page says that some may have been.

Your agent: public values, never secrets

listEnv gives your agent the names, scopes and the secret flag — never a value, not even a non-secret one. A public value — an address, a feature flag, a key meant to be public, a public certificate — a coding agent on your computer can save itself with setPublicEnv and remove with deletePublicEnv; a chat you connected by Tofu's address hands you the Keys & settings link for it instead. Tofu refuses one whose name or value looks like a secret, as it is or base64-encoded; changing a value or its scopes, or removing one, needs your agreement for that exact key; and the change applies from the app's next deploy. A secret your agent never handles: manageEnvironment hands you the dashboard address for that exact app, and you type it there.

That is deliberate: a secret's value is never returned by Tofu's API or stored in its database, so it is never in a chat, a tool result or a transcript. For the same reason no tool reads back, changes or deletes a hidden value — an agent that could remove configuration it cannot restore could break an app it cannot fix.

What Tofu does not do with values

  • Show a secret again. Neither the dashboard nor your agent can read a secret’s value back; to change it, save a new one.

  • Set a reserved key. Keys starting with VERCEL_ are reserved, and Tofu refuses them.

  • Save two places at once. The provider and Tofu’s records are not one transaction: if a save fails after the provider accepted it, Tofu reports the failure, and saving again reconciles it.

  • Take a secret from your agent. No tool writes, reads back or deletes a hidden value: a secret is typed in the dashboard, and a coding agent on your computer saves public values only.