Skip to main content

Bundles

TL;DR

A bundle is a named collection of environment variables (keys) that you deliver together to a developer, service, or demo environment.

Why bundles matter

  • Organize secrets by role, environment, or project (for example, dev/api, prod/web).
  • Make least-privilege access easy: grant only the bundle(s) a user needs.
  • Reuse keys across bundles to avoid duplication and simplify rotation.

When to use bundles

  • Separate development and production credentials.
  • Provide designers with safe demo values (see Designer Demo recipe).
  • Scope short-lived credentials for CI or AI sandboxes.

How bundles work (quick)

  1. Create keys in the key library (name + encrypted value).
  2. Create a bundle and attach keys (order and metadata maintained).
  3. When a CLI request is approved, the server selects the requested keys from the bundle, decrypts them in memory, encrypts them to the CLI public key (sealed box), and stores the ciphertext in Redis for the CLI to fetch.

Bundle manifest example

# bundle.yaml
name: my-project/dev
description: Development bundle for backend
tags: [dev, backend]
secrets:
  - DATABASE_URL
  - API_KEY
  - FEATURE_FLAG

Best practices

  • Keep bundles small and purpose-focused. Prefer multiple small bundles (service, frontend, demo) over one large bundle.
  • Use descriptive names (team/project/env or project/env/role) to make intent clear.
  • Reuse keys across bundles when the same secret is needed in multiple contexts. Rotate the key value, not every bundle.
  • Avoid storing long-lived admin credentials in developer bundles.

Common operations (CLI & UI)

  • Create bundle (UI): Bundles → Create bundle
  • Create bundle (API): POST /api/v1/bundles with { name, description }
  • Attach existing key to bundle (UI): Bundle → Attach key
  • Export (dev mode): GET /api/v1/bundles/:id/export?format=env&reveal=1 (DEV only)

Troubleshooting

Problem: Bundle appears empty in the UI

  • Solution: Confirm keys were attached. Check bundle_keys relationships in the admin UI or API.

Problem: CLI request suggests a different bundle than expected

  • Solution: Verify the suggested_bundle_id field in the request context (GET /api/v1/requests/:id/context).

Next steps

  • Read the Onboarding recipe to see bundles used during new-hire setup: ../recipes/onboard-new-dev.md
  • Learn about the approval flow that securely delivers bundle values: ../device-approval.md