---
status: active
owner: platform
last_reviewed: 2026-09-29
supersedes: []
---
# Secrets management
<!-- wiki:featured -->

**Never commit real credentials to git.** This document explains what secrets exist, where they live on the server, and what you must restore from an **offline vault** if the VM is lost.

## Three-layer model

```
┌─────────────────────────────────────────────────────────┐
│  Git (venture-studio)     → code, .env.example, docs      │
├─────────────────────────────────────────────────────────┤
│  VM disk (gitignored)   → .env, .env.local, rclone conf │
├─────────────────────────────────────────────────────────┤
│  Offline vault          → password manager / encrypted    │
│                           copy for disaster recovery     │
└─────────────────────────────────────────────────────────┘
```

## Gitignored files (on VM only)

| File | Product / scope |
|------|-----------------|
| `studio/.env` | Studio-wide |
| `products/saas/astra-ai-cos/.env` | Astra backend |
| `products/saas/astra-ai-cos/frontend/.env.local` | Astra Next.js server |
| `products/saas/careeros/.env` | CareerOS |
| `dashboard/.env.local` | Studio launcher |
| `**/SECRETS.local.md` | Operator notes (any product) |

Safe templates in git:

- [docs/products/saas/astra-ai-cos/SECRETS_REGISTRY.template.md](../products/saas/astra-ai-cos/SECRETS_REGISTRY.template.md)
- [templates/SECRETS_OFFLINE_VAULT.template.md](./templates/SECRETS_OFFLINE_VAULT.template.md)

## Credential categories to store offline

Copy [templates/SECRETS_OFFLINE_VAULT.template.md](./templates/SECRETS_OFFLINE_VAULT.template.md) into your password manager. Minimum set for full recovery:

1. **GitHub** — deploy keys or SSH key used to clone `venture-studio`
2. **Postgres** — `DB_PASSWORD`, superuser if used for migrations
3. **JWT / auth** — `ASTRA_JWT_SECRET`, `ASTRA_DEV_STATIC_BEARER` (dev only), IdP settings
4. **LLM** — `OPENAI_API_KEY`, LiteLLM master key, provider keys in `litellm_config.yaml` env
5. **Microsoft 365 OAuth** — app registration client ID/secret/tenant (Astra connectors)
6. **rclone** — Koofr (or other) remote credentials for backup restore
7. **DuckDNS** — token for `astra-venky.duckdns.org`
8. **Encrypted backup** — rclone crypt password if `VENTURE_BACKUP_ENCRYPT_REMOTE` is enabled
9. **Gotify / push** — if digest notifications enabled

## Setting up secrets on a new VM

```bash
cd ~/studio
cp products/saas/astra-ai-cos/.env.example products/saas/astra-ai-cos/.env
# Edit .env — paste values from offline vault only on the server, never into git

cp products/saas/astra-ai-cos/frontend/.env.example products/saas/astra-ai-cos/frontend/.env.local
# Edit .env.local for BACKEND_INTERNAL_URL etc.
```

Validate names (not values) against `.env.example` files in each product.

## Rotation

If a secret was ever committed or leaked:

1. Rotate immediately at the provider
2. Update VM `.env` files
3. Restart affected services
4. If the repo was public, consider history rewrite (`git filter-repo`)

See [GIT_AND_REPO_HYGIENE.md](./GIT_AND_REPO_HYGIENE.md).

## Related

- [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md) — when vault + backups are needed together
- Astra variable map: [SECRETS_REGISTRY.template.md](../products/saas/astra-ai-cos/SECRETS_REGISTRY.template.md)