Secrets

Secrets let your agent use sensitive values like API keys and tokens in shell commands without ever seeing the actual values. The agent writes $SECRET_NAME in commands, Letta Code substitutes the real value at execution time, and scrubs it from all output before the agent sees the result.

Managing secrets

Use the /secret slash command to manage your agent’s secrets:

> /secret set OPENAI_API_KEY sk-proj-abc123...
Secret '$OPENAI_API_KEY' set.

> /secret list
Available secrets (2):
  $OPENAI_API_KEY
  $GITHUB_TOKEN

> /secret unset GITHUB_TOKEN
Secret '$GITHUB_TOKEN' unset.

Naming rules

Secret names must be uppercase letters, numbers, and underscores only, starting with a letter or underscore. Names are automatically normalized to uppercase.

Valid	Invalid
API_KEY	api-key (hyphens not allowed)
MY_TOKEN_123	123_TOKEN (cannot start with a number)
_PRIVATE	my secret (no spaces)

Using secrets in commands

Reference secrets with $SECRET_NAME syntax in any shell command. Your agent can discover available secrets through its memory and use them naturally:

> Can you call the OpenAI API to list my models?

Agent runs: curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

The agent writes the command with $OPENAI_API_KEY. Letta Code substitutes the actual key value when executing the command, then scrubs the value from the output. The agent never sees sk-proj-abc123... in any tool result.

Which tools support secrets?

Secret substitution applies to all shell-based tools:

• Bash / ShellCommand
• TaskOutput

Read-only tools like Read, Grep, and Glob do not perform secret substitution since they don’t execute shell commands.

How it works

Secrets are protected through multiple layers:

Substitution at execution time

When the agent calls a shell tool, Letta Code scans the command arguments for $SECRET_NAME patterns and replaces them with the actual values right before execution. The agent’s tool call in the conversation history always shows the $SECRET_NAME placeholder, never the real value.

Output scrubbing

After a shell command runs, Letta Code scans all output (stdout, stderr, and the full tool response) for any occurrence of a secret value and replaces it with $SECRET_NAME. This prevents accidental leaks even if a command echoes the value.

Memory integration

Your agent’s memory includes a list of available secret names so it knows what secrets are available. Secret values are never written to memory.

## Available Secrets

Use `$SECRET_NAME` syntax in shell commands to reference these secrets:

- `$OPENAI_API_KEY`
- `$GITHUB_TOKEN`

Server-side storage

Secrets are stored on the Letta server as part of the agent, not on your local machine. They are fetched and cached in memory when Letta Code starts.

Because secrets are tied to the agent, they are available anywhere you use that agent. If you set a secret on your laptop and then connect to the same agent from a different machine, the secret is already there. This makes it easy to share credentials across devices without reconfiguring each one.

Input redaction

When you run /secret set KEY value, the value is redacted from the command history. Other users reviewing the conversation will see /secret set KEY ***.

See also

• Slash commands - Full list of built-in commands
• Permissions - Control what tools your agent can use