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 ports and other runtime plumbing that users do not need to manage.

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.

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.

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

Both kinds have reversible history

Each update creates a new version. Revert or redo from history when a value breaks the running application. A Config or Secret change reconciles affected Services without rebuilding the code.

Changing kind 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.

Project values are runtime only

Project Config and Secrets are delivered when the Service starts. They do not 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. Build time Secrets are not supported because build layers, caches, and output can retain them.

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.

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