Skip to main content
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:
AspectImplementation
AlgorithmAES-256-GCM (authenticated encryption)
Key derivationscrypt from machine-specific data
Per-secret IVEach secret has a unique initialization vector

​
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

AspectValue
Location~/.catty/secrets.json
Permissions0600 (owner read/write only)
Formatv1:<iv>:<authTag>:<ciphertext>

​
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

When creating API tokens, only grant the permissions your workflow needs.
Update your secrets regularly with catty secrets remove and catty secrets add.
The file is encrypted but should still be treated as sensitive. Never commit it to version control.

​
See Also