capy run: Inject Decrypted Secrets at Runtime

​

Synopsis

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

​

Description

​

Two modes

​

Local mode (default)

1. Reads .env from the current working directory.
2. If nothing in .env is encrypted, spawns the child right there - no key, no keep.lock, no network.
3. Otherwise reads keep.lock in that same directory to learn which org and project it belongs to.
4. Resolves your project key. On a cloud or BYOC profile that means authenticating silently against your existing session (refreshing the access token if it has expired) and resolving the key through the Capy service. On a local-only profile it happens entirely offline from your local key, with a passphrase prompt if the session is locked.
5. Decrypts each capy:… snippet in .env and spawns the child with the decrypted values set in its environment.

​

Deployed mode

• SECRETS_BLOB and PROJECT_KEY are emitted by the token-and-instructions flow.
• _SECRETS_BLOB and _PROJECT_KEY are also supported; when both complete pairs are present, Capy uses the underscore-prefixed pair.

1. Parses the selected secrets blob locally - extracts the deploy ID, the service-held outer blob, and the encrypted env map.
2. Posts the outer blob to POST /deploy/{deployId}/decrypt on the Capy service. The service verifies the deploy token isn’t revoked and returns a derived service key.
3. Combines the selected project key with the service key to derive the decrypt key, then AES-GCM-decrypts the env map.
4. Spawns the child with those values set in its environment.

​

Behavior

• Forwards SIGINT, SIGTERM, and SIGHUP to the child.
• Exits with the child’s exit code.

• Deployed mode with SECRETS_BLOB / PROJECT_KEY: variables already set in the environment win over decrypted values. Platform-level overrides stay sovereign.
• Deployed mode with _SECRETS_BLOB / _PROJECT_KEY: decrypted values win over same-named values already in the environment. This lets a platform retain an older plaintext variable while the new runtime pair takes effect.
• Local mode: plaintext keys in .env follow the same rule - the parent environment wins. Encrypted capy:… values do not: they’re re-applied after the merge, so a project secret always overrides a same-named variable inherited from your shell.

​

Examples

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

# Python
capy run -- python app.py
capy run -- python -m uvicorn main:app

# Go
capy run -- go run .
capy run -- ./my-binary

# Ruby
capy run -- bundle exec rails server

# Rust
capy run -- cargo run

# Shell script
capy run -- ./deploy.sh

​

In containers

ENTRYPOINT ["capy", "run", "--"]
CMD ["python", "app.py"]

​

Next.js on Vercel

const { existsSync } = require("fs");
const { join } = require("path");

const envPath = join(__dirname, ".capy", "next-env.js");
const capyEnv = existsSync(envPath) ? require(envPath) : {};

module.exports = { env: capyEnv };

​

See also

• Running your app - the full runtime story
• Deploying - how SECRETS_BLOB and PROJECT_KEY reach your platform