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

Via SDK

Interactive Mode

Avoid exposing secrets in shell history:

Using Secrets in Agents

Secrets are available as environment variables:

Built-in Secrets

Castari automatically provides:
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

Values are never displayed — only keys and metadata.

Updating Secrets

Set the same key again to update:
Changes take effect on the next invocation.

Deleting Secrets

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:

Secrets in CI/CD

Example GitHub Actions workflow:

See Also

cast secrets

CLI reference

Secrets API

SDK reference