Secrets

How Secrets Work

Each agent has an isolated .env file in its workspace directory. When the agent's container starts, all secrets defined in this file are loaded as environment variables, and the agent accesses them through standard environment variable reads (e.g., process.env.MY_API_KEY in Node.js or os.environ["MY_API_KEY"] in Python). This keeps credentials out of the system prompt and session messages.

Secrets are scoped to a single agent; other agents cannot read them.

When Agents Need Secrets

Common scenarios:

• Third-party API keys: services like GitHub, Jira, Slack, or any REST API the agent calls.
• Database credentials: connection strings or passwords for databases the agent queries.
• Custom tool authentication: tokens required by skills or tools installed on the agent.
• Service accounts: credentials for cloud platforms (AWS, GCP, etc.) when using direct API access rather than connected accounts.

Some skills declare required environment variables during installation; Gamut prompts for the necessary secrets when such a skill is installed.

Agents can also request secrets at runtime with the Request Secret tool. When an agent needs a credential that is not yet configured, it prompts in the chat for the value.

Managing Secrets

Opening the Secrets Tab

1. Navigate to the agent's home page.
2. Click the gear icon to open Settings, then select the Secrets tab.

Alternatively, click Secrets in the Extras panel on the right side of the agent home page.

Adding a Secret

1. In the Secrets tab, fill in the Add New Secret form:
   • Key Name: a human-readable label (e.g., "My API Key"), converted to an environment variable name automatically.
   • Value: the secret value. Click the eye icon to toggle visibility.
2. Review the generated environment variable name shown below the Key Name field.
3. Click Add Secret.

Key Name to Environment Variable Conversion

Gamut converts the human-readable key name into a valid environment variable name:

The rules:

1. Convert to uppercase.
2. Replace any non-alphanumeric characters with underscores.
3. Trim leading and trailing underscores.
4. Collapse consecutive underscores.

Duplicate environment variable names are rejected. If a "(duplicate)" warning appears, choose a different key name.

Updating a Secret

1. Find the secret in the Existing Secrets list.
2. Click Update next to the secret.
3. Enter the new value in the field that appears.
4. Click Save.

Secret values are never displayed after saving; they always appear as masked dots.

Removing a Secret

1. Find the secret in the Existing Secrets list.
2. Click the trash icon.

The secret is removed immediately, and the agent no longer has access to the environment variable in new sessions.

Storage Format

Secrets are persisted in a standard .env file inside the agent's workspace:

# Superagent Secrets
# Format: ENV_VAR=value  # Display Name
 
GITHUB_TOKEN=ghp_abc123  # GitHub Token
SLACK_BOT_TOKEN="xoxb-my-token"  # Slack Bot Token
DB_PASSWORD=s3cret

Values containing spaces, quotes, hash characters, or newlines are wrapped in double quotes with proper escaping. The human-readable key name is stored as an inline comment when it differs from the environment variable name.

Security Considerations

• Secrets are stored on disk in the agent's workspace directory. They are not encrypted at rest by Gamut itself; rely on the operating system's disk encryption for at-rest protection.
• The Export Full Agent feature in Settings > General includes secrets in the exported .agent archive. The export dialog warns about this. Only share full agent exports with trusted parties.
• The Export as Template feature does not include secrets. Templates are safe to share.
• In multi-user (auth mode) deployments, only agent owners can view and manage secrets.