Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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, not value. The runtime resolves the actual value, passes it to the tool, and redacts it from all output. This means the agent can use secrets without exposing them to inference providers. 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

When the agent needs to use a secret, it creates a reference to the stored secret in the tool argument. You do not need to type the reference or expose the raw value. If you see a generated secret reference in logs or tool output, it means the agent referenced a stored secret.
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 a user adds the credential, 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 secrets list
pool secrets add <secret-name> -d "<description>"
pool secrets get <secret-name> --show-value
pool secrets edit <secret-name> --name <new-name>
pool secrets 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 automatically uses secrets interpolation when it needs to pass a secret in a tool argument. To have the agent use a specific secret, mention the secret by name in your prompt. For example, the agent might use the following syntax to call the GitHub API. The exact syntax can change between versions:
GitHub API example
curl -H 'Authorization: Bearer ⟦secret⋮github_token⟧' https://api.github.com/user
At runtime, Poolside replaces the interpolation syntax with the actual token value before it executes the tool and redacts the token from the output. This means the secret value is not sent to inference providers or stored in trajectory logs.

​
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. For a complete reference of supported settings.yaml keys, see Settings file reference. 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. Administrators can manage organization redaction patterns in the Poolside Console, and users can add user patterns or control fallback default patterns in settings.yaml. For more information, see Redaction patterns.