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:
| Variable | Description |
|---|
ANTHROPIC_API_KEY | Your 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...
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
