> ## Documentation Index
> Fetch the complete documentation index at: https://capy.sc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How capy run Decrypts Secrets at Runtime

> How capy run injects decrypted secrets into your process — local mode reads .env plus the keyring; deployed mode unwraps SECRETS_BLOB at startup.

Capy's runtime story is one command: **`capy run -- <your command>`**. It wraps any process, decrypts `.env` in memory, and hands the plaintext values to the child as ordinary environment variables. Your app reads `process.env` (or `os.environ`, or `ENV[...]`, or whatever your language uses) - no library to import, no SDK per language.

## The pattern

```bash theme={null}
capy run -- <your command> [args...]
```

Capy:

1. Reads `.env` from the current directory.
2. Resolves the project key from the first available source (local keyring, deploy code env var, or explicit `CAPY_KEY`).
3. Decrypts every `capy:…` snippet.
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.

The plaintext lives only in the child process's memory - never written to disk.

## Examples

```bash theme={null}
# 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

Put `capy run` in your scripts once and forget about it:

```json theme={null}
{
  "scripts": {
    "dev": "capy run -- next dev",
    "start": "capy run -- node server.js",
    "test": "capy run -- bun test"
  }
}
```

Then `bun run dev` / `npm run dev` / `pnpm dev` all work as usual; the wrapping is invisible.

## Precedence: shell env vs. decrypted `.env`

If a variable is already set in the shell (or by the platform running `capy run`), `capy run` leaves it alone. Only variables that appear in `.env` as `capy:…` snippets get decrypted into the child's environment. That matches dotenv's usual precedence: explicit env wins over file-based env.

## What's next

<Columns cols={2}>
  <Card title="Deploying" icon="rocket" href="/using/deploying" horizontal>
    How the runtime key source gets set in production.
  </Card>

  <Card title="capy run (CLI reference)" icon="terminal" href="/cli/run" horizontal>
    Flags and behavior details.
  </Card>
</Columns>