Config, secrets, and environment variables

Your code keeps using ordinary environment variables while Tokay controls where their runtime values come from. Project Config holds values people and agents may inspect. Project Secrets protect credentials that must remain hidden after entry.

Last updated

AI agent? Start with llms.txt.

No Tokay SDK is required. Applications use their normal language interface, such as process.env.API_BASE_URL or os.environ["DATABASE_URL"].

Every variable has a need and a source

Tokay detects whether an environment variable is required, optional, or already has a code default. That policy is separate from where its value comes from.

  • Project Config supplies user managed nonsecret values such as modes, limits, flags, and public service URLs.
  • Project Secrets supply credentials and any value you are not certain is safe to expose.
  • Infrastructure values supply database connections and credentials generated by Tokay.
  • Platform values supply the port and, when the code's own default is missing or wrong for a deployed app, a value Tokay sets for you, such as production for NODE_ENV. A Config or Secret with the same name, or an override for that variable, replaces it. Remove that and Tokay's value comes back.

The Service Environment tab shows the effective source and whether the variable is ready. A required value with no source blocks deployment instead of producing a Service that fails at startup. Competing sources remain a visible conflict until you choose which one the Service should use.

Ignoring a variable or clearing its override names no new value, so something else takes over, such as Tokay's value, the code's own default, or a database, or the Service runs without it. When the Service receives a value you set, Tokay shows what it will receive instead and asks before anything changes.

When your code reads a variable Tokay missed, choose Add a variable on the Service Environment tab so the Service receives the Project value of that name.

New values default to Secret

Choose Config only when the value is safe for people and agents who can read the Project source code. Config is stored as readable text, and anyone whose access allows reading the Project source can inspect it through the dashboard and API.

Secrets are encrypted at rest and write only through the product API. Tokay does not write them into source, bake them into builds, or print them into platform logs. Your application can still print any value it reads, so application logs must not include credentials.

When Tokay finds a likely credential committed in source, it proposes changing the code to read an environment variable and moving the value into secure storage. The source change requires approval.

Project values can be shared or routed

Config and Secrets belong to a Project so related Services can share one value. A web Service and scheduled job can both receive the same API_URL, for example.

An override can route one Service environment variable to a different Project Config or Secret. This keeps variants explicit without copying values into each Service. When a web app and a worker both read LOG_LEVEL but need different values, route the worker's LOG_LEVEL to a Config named WORKER_LOG_LEVEL, and the code keeps reading one name.

Config and Secret share one namespace inside a Project. One name cannot exist as both types at the same time.

Both types have reversible history

Each update creates a new version. A Config or Secret change redeploys the Services that use it without rebuilding the code, with no downtime unless a Service keeps an embedded database such as SQLite in its Saved files (Deploys and rollback). If the new value stops the app, that deploy fails and the previous one keeps serving, so revert or redo from history to fix it.

Changing type is not an edit. Replacing Secret with Config or Config with Secret requires a new value, deletes the old identity and history, and keeps only the explicit Service overrides. Moving Config to Secret cannot undo earlier exposure, so rotate a value if it became sensitive.

Previews can use their own values

A Project that previews its pushes runs each preview with your live Config and Secrets. Give a value a preview value, such as a test API key, and only the preview uses it. Your live app keeps its own (Try changes in a preview).

When project values arrive

Project Config and Secrets are delivered when the Service starts. A variable the code reads while it builds, such as a token a static site's build uses to fetch its content, gets its value at build time too: the build receives it as a BuildKit secret, so it isn't kept in the image unless the code writes it out, Secrets are masked in build output, and changing the value rebuilds the Service. Values never change an existing frontend bundle.

Public values with prefixes such as VITE_, NEXT_PUBLIC_, and REACT_APP_ are usually compiled into browser assets. Commit those production values to source and push a new build. The exception is a sibling Service's address: Tokay builds a same-origin path to it into a single-page frontend, and rebuilds when its routing changes (App access control for agents). A Config or Secret of such a name reaches no bundle, so it never clears the missing value Tokay reports for the variable. When the variable is another Service's address, route it to that Service and Tokay builds the address in. Otherwise commit the value.

Code rollback keeps current values

Rolling back a deployment restores code and build output. It does not rewind Project Config, Secrets, or managed resource credentials. Current runtime values stay current so rollback does not revive a revoked key or an obsolete endpoint.

When new code stops reading a stored value, Tokay keeps it until you decide to remove it. The Project Environment tab warns that a value no Service reads changes nothing.

See Databases for infrastructure generated connections and How Tokay sets up your app for detection and review.