Secrets vault

The secrets vault stores arbitrary NAME=value pairs encrypted at rest and injects them as environment variables into agent containers at task start. You scope each secret to either all your profiles or a specific subset.

Use cases:

• API keys for tools to use (Supabase service key, GitHub PAT, Twilio token).
• Provider-specific config (Stripe webhook secret, AWS credentials).
• Database connection strings for read-only ledgers a profile owns.

Shape

Field	Notes
id	sec_<nanoid>.
name	Uppercase env-var name. Must match ^[A-Z_][A-Z0-9_]*$.
value	Encrypted AES-256-GCM under ENCRYPTION_KEY. Never returned in list responses.
scope	all (default) — every profile of yours gets it as env. agents — only the listed profile_ids.
profile_ids	When scope=agents, the granted profile ids.

Authoring

Dashboard: Settings → Secrets → Add. The modal has a scope picker identical to integrations’ scope picker.

API:

POST /v1/secrets
Content-Type: application/json

{
  "name": "STRIPE_WEBHOOK_SECRET",
  "value": "whsec_…",
  "scope": "agents",
  "profile_ids": ["prof_billing"]
}

How agents see secrets

At task start, the orchestrator calls SecretVaultService.getDecryptedForProfile(userId, profileId) which:

1. Selects all secrets for the user.
2. Filters by scope: all rows always included; agents rows included only when profileId is in profile_ids.
3. Decrypts each value.
4. Returns a Record<string, string> env map.

The orchestrator merges this with the profile’s setup_commands env and the platform’s baseline env (Anthropic API key, MCP URLs + tokens) before passing the result to Docker as --env.

What secrets are NOT for

• Notification routing — use Integrations.
• MCP credentials — use Integrations (Gmail OAuth, Teller mTLS cert).
• Per-task injection — secrets are profile-scoped, not session-scoped. If you need per-session config, encode it in the task prompt.

Rotation

Updating a secret’s value via PATCH /v1/secrets/:id is immediate — the next task on any granted profile sees the new value. Old containers (paused / running) keep the old value until they get a fresh process tree.

To delete cleanly, DELETE /v1/secrets/:id.

Caution

Secrets are dropped into agent containers as plain environment variables. If a custom tool prints process.env to logs or sends it over an outbound API call, you’ve leaked. Audit your tools.

Same scope model as integrations

The scope / profile_ids fields work identically to Integrations. One mental model, two surfaces.