Environment and Credential Pattern
Standard pattern for how Brainforge manages environment variables and credentials across local development, cloud agents, CI/CD, and deployed services.
Core rule
Use 1Password vault items as the durable source of truth for credentials, and use op to resolve them at runtime.
Do not treat checked-in .env files as the canonical store for credentials.
Preferred model by surface
| Surface | Source of truth | Runtime loader | Identity model | Notes |
|---|---|---|---|---|
| Local development | 1Password vault items | op run, op read | Human desktop auth | Fine for non-prod human workflows. |
| Codex / Cursor / OpenCode agents | 1Password vault items | op-based injection | Scoped service account | Do not rely on inherited broad env sets. |
| CI/CD | 1Password vault items | op-based injection or platform sync | Scoped service account | Separate non-prod and prod access. |
| Deployed services | 1Password vault items upstream | Platform secret injection / synced env | Machine identity | Prefer platform-native injection once deployed. |
1Password Environments
1Password Environments are optional.
Use them when they help with:
- shared stage-level config
- onboarding
- curated project groupings
Do not require them to mirror every underlying credential item one-for-one. The canonical value should still live as a normal 1Password item/field unless there is a specific reason to do otherwise.
Trust boundaries
Separate identities and access by trust boundary:
- Brainforge shared engineering
- staging vs production
- each client pilot or client-specific delivery context
Do not use one broad token across Codex, Cursor, OpenCode, Railway, and client pilots if the access can be scoped tighter.
Client work
Use client vaults for client-specific credentials and auditable client access.
Keep shared Brainforge platform credentials in the Brainforge AI Team vault unless compliance or contract language requires a stricter boundary.
Do not allow one client pilot to inherit another client’s credentials through a shared agent session or shared service account.
Tooling notes
- Doppler is a reference point for the “centralized environment injection” model. Brainforge currently gets most of that value from 1Password +
opwithout adding a second control plane. - Varlock is a useful reference point for typed env/schema enforcement and sensitivity metadata. It can sit on top of 1Password later if we want stronger application-side typing and redaction ergonomics.
- If a client requires a different underlying credential system in the future, a Varlock-style layer could also sit on top of other secret managers such as AWS Secrets Manager, GCP Secret Manager, or similar provider-native stores without changing the higher-level app env/schema pattern.
Minimum verification after any cutover
- Confirm the workload can start with the intended environment values present.
- Confirm the workload used the intended identity path: desktop auth for local human dev, or scoped service account for automation.
- Confirm no unrelated production or client credentials are readable from that surface.
- Confirm any renamed or deprecated item has a rollback path.