> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration and secrets

> Give your agent API keys and settings without putting them in the repository: secrets and variables, bulk paste from .env, and when a change takes effect.

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](/deploy/auto-deploy) 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](/deploy/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:

```yaml agent.yml theme={null}
env:
  required:
    - OPENAI_API_KEY
  optional:
    - LOG_LEVEL
```

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](/production/errors#credential_detected).

## Secrets during the build

Secrets are not available to `build.commands`, and the [smoke test](/deploy/builds#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:

| Variable | Holds |
| - | - |
| `ONECORTEX_AGENT_ID` | The agent's ID, `agt_...` |
| `ONECORTEX_VERSION` | The ID of the build that released the running version, `bld_...`, or of the deployment for a rollback. It changes on every release |

## 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](/production/limits).