Skip to main content
Your agent reads its configuration as environment variables: os.environ["OPENAI_API_KEY"] in Python, process.env.OPENAI_API_KEY in TypeScript. You set the values on the agent’s Config tab, never in the repository.

​
Secrets and variables

Each entry is one of two kinds:
  • Secret: a model API key, a database password, a token. Stored encrypted, and never shown again once saved: not to you, not in the list, not in logs.
  • Variable: a setting that is not sensitive, such as a model name or a log level. Stored as plain text and shown in the list.
Both reach your agent the same way, as environment variables. Choose Secret for anything you would not paste into a chat.

​
Add an entry

On the agent’s Config tab, click Add, and enter:
  • Key: upper case letters, digits and underscores, not starting with a digit, such as OPENAI_API_KEY.
  • Kind: Secret or Variable.
  • Value.
To add many at once from a .env file, click Bulk edit and paste it: one KEY=value per line, and lines starting with # are ignored. Choose whether everything in the paste is a secret or a variable. A file with both goes in as two pastes.

​
When a change takes effect

Configuration is applied when a version is released, so a change reaches your agent on its next deployment:
  • With automatic deploys on, Onecortex deploys for you, and the tab says Redeploying automatically.
  • With them off, the tab says Configuration changed. Deploy to apply. Click Deploy.
The version that is live keeps its old configuration until then. Configuration is not part of a version. Rolling back to an older version runs its code with today’s configuration, and the rollback dialog warns you when configuration has changed since that version was built. See Versions and rollback.

​
Declare what your agent needs

List the keys your agent needs in agent.yml, so a missing one is flagged before it fails:
agent.yml
A required key with no entry is shown on the Config tab as Required by agent.yml, with Set value, and validation warns: `OPENAI_API_KEY` is declared in env.required but is not configured for this agent. It is a warning, so the build goes on. Never put the value itself in agent.yml: a value that looks like a credential fails validation with credential_detected. See Errors.

​
Secrets during the build

Secrets are not available to build.commands, and the smoke test runs your agent with every key set to a placeholder, never the real value. An agent that calls its model during the smoke test gets an authentication error from the model. That is fine as long as your agent answers: the smoke test checks that it answers, not what it says. Code that crashes when a key is invalid fails the smoke test, so catch the model’s error.

​
Set for you

Two variables are set on every agent, and you cannot set them yourself:

​
Limits

  • 45 entries per agent, secrets and variables together: You are using <n> of 45 configuration entries. Remove one to add another.
  • PORT, and platform prefixes such as ONECORTEX_ and OTEL_, are reserved: This key name is reserved by the platform. Choose another.
All limits are on Limits.
Last modified on September 28, 2026