> ## Documentation Index
> Fetch the complete documentation index at: https://docs.castari.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Managing environment variables for agents

# 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

```bash theme={null}
cast secrets set my-agent OPENAI_API_KEY sk-abc123...
```

### Via SDK

```typescript theme={null}
await client.secrets.set('my-agent', 'OPENAI_API_KEY', 'sk-abc123...');
```

### Interactive Mode

Avoid exposing secrets in shell history:

```bash theme={null}
cast secrets set my-agent OPENAI_API_KEY
# Prompts for value securely
```

## Using Secrets in Agents

Secrets are available as environment variables:

```typescript theme={null}
// 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 |

<Tip>
  You don't need to set `ANTHROPIC_API_KEY` — Castari injects it automatically so your agents can use Claude.
</Tip>

## 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

```bash theme={null}
cast secrets list my-agent
```

```
KEY                  CREATED
OPENAI_API_KEY       2024-01-15 10:30:00
DATABASE_URL         2024-01-15 10:30:00
```

<Note>
  Values are never displayed — only keys and metadata.
</Note>

## Updating Secrets

Set the same key again to update:

```bash theme={null}
cast secrets set my-agent OPENAI_API_KEY sk-new-key...
```

Changes take effect on the next invocation.

## Deleting Secrets

```bash theme={null}
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:

```bash theme={null}
# .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:

```yaml theme={null}
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

<CardGroup cols={2}>
  <Card title="cast secrets" icon="terminal" href="/cli/secrets">
    CLI reference
  </Card>

  <Card title="Secrets API" icon="code" href="/sdk/secrets">
    SDK reference
  </Card>
</CardGroup>