How to give your agent the API keys and tokens it needs, stored safely per project.

Secrets are private values — API keys, tokens, connection strings — that belong to a project and are made available to your agent during a session. They're stored encrypted, never written into your project's files, and provided to each session as it starts.

How a secret works

A secret has two parts in different places:

The name is declared in your manifest (kortix.toml). Safe to commit — it's only a label like OPENAI_API_KEY.
The value is set separately in the Secrets Manager. Encrypted, never in your repo.

Anyone reading your project can see which secrets it expects, but no one can read the values out of the code.

Add a secret

Declare the name in the manifest

In kortix.toml, add the name under [env]. List it as required if the agent can't work without it, or optional if it's nice to have:

[env]
required = ["DATABASE_URL"]
optional = ["OPENAI_API_KEY", "WEBHOOK_SLACK_SECRET"]

Set the value

Open the Secrets Manager and enter the value for that name. It's encrypted as soon as you save.

Start a session

The next session receives every set secret automatically, read like any environment variable.

Required vs optional

Required — flagged in the Secrets Manager when missing. Use for values the agent genuinely can't work without.
Optional — shows up so you can fill it in, with no warning if empty.

required is a contract with your team about what a project needs, not a lock. Keep the list to the values that truly matter.

Rotating a secret

Set the new value in the Secrets Manager. It takes effect on the next session; sessions already running keep the value they started with.

Under the hood

Secrets are encrypted at rest with AES-256-GCM and injected as plain environment variables into the sandbox at session boot. Names must be env-var-shaped, and the KORTIX_* prefix is reserved for platform values. From the CLI: kortix secrets set NAME=VALUE upserts a value, kortix secrets ls lists what's declared and set, and kortix env push --from .env bulk-uploads a dotenv file. See the secrets reference.

Managing secrets