Skip to main content

​
Overview

Secrets let you store sensitive values such as API keys, tokens, and credentials that agents can use at runtime. When an agent needs a secret, it references it by name. The runtime resolves the actual value, passes it to the tool, and redacts it from all output before the agent or trajectory logs see it. Secrets are available in Poolside Assistant, the pool CLI, and the Poolside Console. If a secret is centrally managed in the Poolside Console, start with Credentials. This page explains how agents use sensitive values safely at runtime.

​
How secrets work

1

Store a secret

You store a secret with a name and value, either locally or through the Poolside Console.
2

Agent discovers secrets

The agent can find available secret names and descriptions, but never the secret values.
3

Agent references a secret

The agent includes the interpolation syntax ⟦secret⋮<name>⟧ in a tool argument and generates it automatically when it needs to use a secret. You do not need to type it. If you see ⟦secret⋮<name>⟧ in logs or tool output, it indicates a secret reference.
4

Runtime resolves the value

Poolside replaces the reference with the actual secret value before the tool executes.
5

Output is redacted

After execution, Poolside scans tool output and replaces the secret value with ⟦SECRET_REDACTED⟧ before the agent sees the output.
The agent never sees the raw secret value in its context window or in trajectory logs.

​
Secret storage

You can store secrets locally or manage them centrally through the Poolside Console. At runtime, Poolside merges both sources.
SourceStored inWho manages itAccess
Local secretsOS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)Individual userRead-write
Remote secrets from credentialsPoolside Console, encrypted at restUsers with Create Credential permissionsRead-only from the agent
When both sources contain a secret with the same name, the local secret takes precedence.

​
Local secrets

Poolside stores local secrets in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). Constraints
  • Name: 6 to 256 characters. Letters, digits, underscores, periods, slashes, and hyphens only.
  • Value: 4 to 2,560 bytes.

​
Remote secrets from credentials

Users with the Create Credential permission can create remote secrets as managed credentials of type Secret in the Poolside Console. Users with the Manage Credentials permission can update existing credentials. Poolside encrypts these credentials at rest. To make a credential available to an agent, a user creates the credential in the Poolside Console and adds it to the agent from the agent configuration page. After the credential is added, the agent can resolve it by name during a session. Agents can only access credentials that are explicitly assigned to them. For more information about creating and managing credentials, see Credentials.

​
Use secrets in the IDE

In Poolside Assistant, configure secrets by typing /secrets in the prompt input box or by clicking the  /  icon and selecting secrets from the commands menu. The secrets appear in two categories:
  • Suggested by sandbox: Secrets declared in the sandbox configuration. Allowed by default.
  • Custom secrets: Secrets you create. Not allowed by default.
Use the checkbox next to each secret to control whether the agent can access it in the current conversation. You can create, edit, and delete secrets from the same menu. You control secret access separately for each conversation.

​
Use secrets in the CLI

​
Manage secrets

pool secret list
pool secret add <secret-name> -d "<description>"
pool secret get <secret-name> --show-value
pool secret edit <secret-name> --name <new-name>
pool secret delete <secret-name>
The add command prompts for the secret value interactively with masked input.

​
Use secrets in agent sessions

During a session, the agent generates secret references using the interpolation syntax ⟦secret⋮<secret-name>⟧ in tool arguments. You do not need to type this syntax. The agent produces it automatically when it decides to use a secret. For example, the agent might run: 
curl -H 'Authorization: Bearer ⟦secret⋮github_token⟧' https://api.github.com/user
At runtime, Poolside replaces ⟦secret⋮github_token⟧ with the actual token value, executes the command, and redacts the token from the output.

​
Secret approval

When an agent references a secret for the first time, Poolside checks whether to allow it:
  1. Settings allow list: If the secret name matches an entry in secrets.allow from your settings.yaml, Poolside auto-approves it.
  2. Session history: If you already approved the secret in this session, Poolside auto-approves it.
  3. User prompt: Otherwise, Poolside asks you to approve or deny the secret.

​
Auto-approve secrets

Add secret names to the secrets.allow list in your settings.yaml to skip approval prompts: 
secrets:
  allow:
    - NPM_TOKEN
    - OPENAI_API_KEY
Matching is by exact name only. Settings file locations
File locationUse this for
.poolside/settings.local.yamlPersonal, project-specific.
Do not commit. Takes precedence over all other files.
.poolside/settings.yamlShared, project-specific.
Commit and share with your team.
~/.config/poolside/settings.yamlPersonal defaults, all projects.
Applies when no project-level settings override it.
For more information about settings file locations and precedence, see Tool permissions.

​
Redaction

When an agent uses a secret during a tool run, Poolside scans tool output for sensitive values and replaces matches with ⟦SECRET_REDACTED⟧ before the agent sees the output. Pattern-based redaction can also apply to text you send to the agent. For more information, see Redaction patterns.