Skip to main content

​
Secrets

Secrets are environment variables injected into your agent at runtime.

​
Why Secrets?

Your agents often need access to:
  • API keys (OpenAI, Stripe, etc.)
  • Database credentials
  • Service tokens
  • Configuration values
Secrets let you provide these securely without:
  • Hardcoding in source code
  • Committing to git
  • Exposing in logs

​
Setting Secrets

​
Via CLI

cast secrets set my-agent OPENAI_API_KEY sk-abc123...

​
Via SDK

await client.secrets.set('my-agent', 'OPENAI_API_KEY', 'sk-abc123...');

​
Interactive Mode

Avoid exposing secrets in shell history: 
cast secrets set my-agent OPENAI_API_KEY
# Prompts for value securely

​
Using Secrets in Agents

Secrets are available as environment variables: 
// Access in your agent code
const openaiKey = process.env.OPENAI_API_KEY;
const databaseUrl = process.env.DATABASE_URL;

// Use with OpenAI
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

​
Built-in Secrets

Castari automatically provides:
VariableDescription
ANTHROPIC_API_KEYYour Anthropic API key for Claude
You don’t need to set ANTHROPIC_API_KEY — Castari injects it automatically so your agents can use Claude.

​
Secret Storage

Secrets are:
  • Encrypted at rest — Using AES-256
  • Never logged — Values are masked in logs
  • Never returned — API only returns key names, not values
  • Scoped per agent — Each agent has its own secrets

​
Listing Secrets

cast secrets list my-agent

KEY                  CREATED
OPENAI_API_KEY       2024-01-15 10:30:00
DATABASE_URL         2024-01-15 10:30:00
Values are never displayed — only keys and metadata.

​
Updating Secrets

Set the same key again to update: 
cast secrets set my-agent OPENAI_API_KEY sk-new-key...
Changes take effect on the next invocation.

​
Deleting Secrets

cast secrets delete my-agent OLD_API_KEY

​
Best Practices

​
Naming Conventions

  • Use UPPERCASE_WITH_UNDERSCORES
  • Be descriptive: STRIPE_SECRET_KEY not KEY1
  • Prefix by service: OPENAI_API_KEY, STRIPE_API_KEY

​
Security

  • Never commit secrets — Use .gitignore for .env files
  • Rotate regularly — Update secrets periodically
  • Limit scope — Only set secrets an agent actually needs
  • Audit access — Review who can manage secrets

​
Development

Keep a .env.example file in your repo: 
# .env.example (committed to git)
OPENAI_API_KEY=your-key-here
DATABASE_URL=postgres://user:pass@host/db

# .env (NOT committed — in .gitignore)
OPENAI_API_KEY=sk-actual-key...
DATABASE_URL=postgres://actual-connection...

​
Secrets in CI/CD

Example GitHub Actions workflow: 
jobs:
  deploy:
    steps:
      - name: Deploy agent
        run: cast deploy

      - name: Set secrets
        env:
          CASTARI_API_KEY: ${{ secrets.CASTARI_API_KEY }}
        run: |
          cast secrets set my-agent OPENAI_API_KEY "${{ secrets.OPENAI_API_KEY }}"
          cast secrets set my-agent DATABASE_URL "${{ secrets.DATABASE_URL }}"

​
See Also

cast secrets

CLI reference

Secrets API

SDK reference