CDX-301f · Module 2

Credential Injection & Rotation

3 min read

Credential injection is the mechanism for providing API keys, tokens, and secrets to Codex Cloud tasks without embedding them in the repository or AGENTS.md. Credentials are pulled from a secrets manager (HashiCorp Vault, AWS Secrets Manager, GitHub Secrets) at task start, injected as environment variables, and destroyed with the microVM when the task completes. The credential never touches disk inside the microVM — it exists only in memory for the duration of the task.

Credential rotation in a Codex Cloud environment requires coordination between the secrets manager and the warm pool. When a credential is rotated, all warm pool snapshots that contain the old credential become stale. The warm pool must be refreshed — new snapshots taken with the new credential — before any tasks attempt to use it. Without this coordination, tasks that resume from a warm snapshot will use the old (revoked) credential and fail with authentication errors. The fix is to tie credential rotation to snapshot refresh: rotate the credential, trigger a pool refresh, verify new snapshots work, then revoke the old credential.

# Credential injection flow

1. Task submitted → orchestrator reads task config
2. Config references credentials by name (not value)
3. Orchestrator fetches values from secrets manager
4. Values injected as env vars into microVM at boot
5. Task executes — credentials available via process.env
6. Task completes → VM destroyed → credentials gone

# Credential scoping

scope: task        # Credential available only during this task
scope: session     # Credential available across tasks in a session
scope: pool        # Credential baked into warm pool snapshots

# Rotation checklist
1. Generate new credential in the external service
2. Update secrets manager with new value
3. Refresh warm pool snapshots (if scope: pool)
4. Verify new credential works in a test task
5. Revoke old credential in the external service
6. Confirm no tasks are using the old credential

Do This

  • Use "task" scope for credentials that change frequently (API keys, short-lived tokens)
  • Tie credential rotation to warm pool refresh to prevent stale-credential failures
  • Audit which credentials each task type uses — over-provisioning credentials increases blast radius

Avoid This

  • Embed credentials in AGENTS.md or the repository — they will be cloned to every microVM
  • Use "pool" scope for credentials that rotate frequently — stale snapshots cause cascading failures
  • Rotate credentials without verifying the new credential works in a test task first