Secret vault

Passwords, API keys and tokens never belong in an agent definition, a prompt or 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, prompts and profiles are stored in Search2o Cloud in plain form and are visible to every developer. A secret written into any of them would be visible to the same people and would leave your enterprise. 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 agent 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 value already read is reused for the cache period, so a rotated file is read after that.

A vault of your own

secretSource set to vault. The agent server reads each secret through the vault hook: an async Python function of your own that takes the secret's name and returns the value, from whatever vault your enterprise runs. Install the function on every agent server and name it on the Hooks page. The Secrets & encryption page refuses the vault source until the hook is set, and the hook is loaded when the agent server starts. Before an agent runs, the agent server calls the hook once for each secret the agent reads, so the values are available when the run starts. Choose this source when your secrets are stored in a vault such as HashiCorp Vault, AWS Secrets Manager or Azure Key Vault, and should stay there.

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. The vault hook receives the name as written. 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.

What the agent server does with a secret

A secret is kept in the agent server's memory for cacheMinutes after it is read, whatever the source, and read again after that. The default is 60 minutes; 0 reads the secret every time, and a negative value keeps it until the agent server stops. 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 UI under Operations › Secrets & encryption.

Name transform