Secrets

Secrets let you securely store sensitive values (API keys, tokens) locally and pass them to your sessions as environment variables.

How It Works

1. You add secrets locally with catty secrets add
2. Secrets are encrypted and stored at ~/.catty/secrets.json
3. When you run catty new, secrets are decrypted and sent to the API over HTTPS
4. Your session receives them as environment variables
5. Secrets are never stored on Catty servers

Quick Start

# Add a secret
catty secrets add MY_API_KEY
# → Enter value for MY_API_KEY: ••••••••

# List secrets (shows names only)
catty secrets list

# Start a session - secrets are automatically passed
catty new

Using Secrets in Sessions

Secrets appear as environment variables:

# In session
echo $MY_API_KEY

Claude can access them in code:

import os
api_key = os.environ.get('MY_API_KEY')

Encryption

Secrets are encrypted using:

Machine Binding

The encryption key is derived from your hostname and home directory. This means:

• Secrets can only be decrypted on the machine they were created on
• Copying secrets.json to another machine won't work
• If you change hostname or reinstall your OS, you'll need to re-add secrets

Storage

Blocked Names

These names are reserved and cannot be used:

• System: PATH, HOME, USER, SHELL, PWD
• Catty internal: CONNECT_TOKEN, CATTY_CMD, SESSION_LABEL
• Cloud credentials: R2_*, AWS_*, FLY_*

Skipping Secrets

Start a session without passing secrets:

catty new --no-secrets

Best Practices

See Also

• GitHub Integration - Special setup for GitHub tokens
• catty secrets - CLI command reference
• catty new - Start session with secrets