Secret vault

Passwords, API keys and tokens must never appear in an agent definition or in a profile. An agent reads a secret at runtime with sys.secret[name], and the Secrets configuration decides where that name is looked up. There are three sources.

Why a vault

Agent definitions and profiles are stored in Search2o Cloud in plain form and are visible to every developer. A secret written into either would be visible to the same people and would leave your organization. With sys.secret, the definition carries only a name, and the value exists only on the agent server, at runtime, in memory.

"headers": { "Authorization": "{ f\"Bearer {sys.secret['OPENAI_API_KEY']}\" }" }

Environment variables

secretSource set to env, the default. The name is transformed (see below) and read as an environment variable of the agent server process. Set the variables before starting the server, from your secret store, your container platform, or a shell profile. The seeded LLM profiles read OPENAI_API_KEY, ANTHROPIC_API_KEY and GEMINI_API_KEY this way. Choose this source when your platform already injects secrets as environment variables.

Files

secretSource set to file. The transformed name is a file path, and the file's contents, trimmed, are the secret. Choose this source when secrets arrive as mounted volumes: a Kubernetes secret, a Docker secret, or a file written by a vault agent. A file can be rotated in place without restarting the server, although a value already read is cached until the server restarts.

Hosted secrets

secretSource set to hosted. Secrets are entered in the GUI, on the Secrets & encryption page, and stored in Search2o Cloud. Hosted secrets require end-to-end encryption. The agent server encrypts each secret with your own key before the secret leaves your organization. The cloud stores and serves only the ciphertext, and the server decrypts the secrets when the server loads the configuration. The cloud never sees a secret in clear. Choose this source when the servers have no secret store of their own and the account's administrators should manage secrets in one place.

The name transform

For env and file, the name an agent asks for is transformed before the lookup: characters matching a pattern are replaced, then the case is converted. With the defaults, sys.secret['my-api.key'] reads my_api_key; set convertTo to upper for the usual environment-variable style. The settings are listed below.

Your own vault

To read from a vault of your own, add a function to the allowlist and call the function from agents. The headers of an LLM or API profile are dynamic strings, so they can call the function too.

What the server does with a secret

A secret is cached in the server's memory after first use. Values read by an agent are never written to traces, logs or reports, and URLs, headers and connection strings are masked before they are logged. A secret read through sys.secret still reaches whatever the agent sends it to, so send secrets only to the services they belong to.

Settings

The Secrets part is edited in the GUI under Operations › Secrets & encryption.

Name transform