How capy run Decrypts Secrets at Runtime

​

The pattern

capy run -- <your command> [args...]

1. Picks a mode from process.env. Either _SECRETS_BLOB with _PROJECT_KEY or the legacy SECRETS_BLOB with PROJECT_KEY enables deployed mode. Each pair must be complete; a half-configured pair is an error.
2. Local mode reads .env from the current directory. It resolves the project key through the Capy service on a cloud or BYOC profile, or from the local key on a local-only profile. Deployed mode parses the selected blob, fetches its service key, and combines it with the matching project key.
3. Decrypts every capy:… snippet in .env (local mode), or the whole encrypted env map (deployed mode).
4. Spawns the child with the decrypted values set in its environment.
5. Forwards SIGINT, SIGTERM, and SIGHUP to the child; exits with the child’s exit code.

​

Examples

# Node
capy run -- node server.js
capy run -- next dev
capy run -- bun test

# Python
capy run -- python app.py
capy run -- pytest

# Go / Rust / binaries
capy run -- go run .
capy run -- cargo run
capy run -- ./my-binary

# Shell scripts that read $DATABASE_URL
capy run -- ./deploy.sh

​

In package.json scripts

{
  "scripts": {
    "dev": "capy run -- next dev",
    "start": "capy run -- node server.js",
    "test": "capy run -- bun test"
  }
}

​

Precedence: shell env vs. decrypted values

• Local mode. Plaintext keys in .env follow dotenv’s usual precedence — a variable already set in your shell wins over the file. Encrypted capy:… values are the exception: they’re re-applied after that merge, so a decrypted project secret always overrides a same-named variable inherited from your shell.
• Deployed mode with _SECRETS_BLOB / _PROJECT_KEY. Decrypted values override same-named values already in the environment.
• Deployed mode with SECRETS_BLOB / PROJECT_KEY. Existing environment values override decrypted values. This is the pair emitted by the token-and-instructions flow.

​

What’s next