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

# Quickstart

> Get envtrap v3.1 protecting your Node.js application in under 60 seconds.

# Quickstart Guide

This guide walks you through installing `envtrap`, running it against your application, understanding its output, and integrating it into your deployment workflow.

***

## Prerequisites

* **Node.js**: `18.0.0` or higher (ESM customization hooks require Node.js 18+).
* **Package Manager**: `npm`, `pnpm`, or `yarn`.

***

## Getting Started

<Steps>
  <Step title="Install envtrap">
    Install envtrap globally, locally as a dev dependency, or execute it on-demand via `npx`:

    <Tabs>
      <Tab title="Global (Recommended)">
        ```bash theme={null}
        npm install -g envtrap
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add -D envtrap
        ```
      </Tab>

      <Tab title="npm (Dev Dependency)">
        ```bash theme={null}
        npm install --save-dev envtrap
        ```
      </Tab>

      <Tab title="npx (No Install)">
        ```bash theme={null}
        npx envtrap run node app.js
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run your application with envtrap">
    Simply prefix your standard startup command with `envtrap run`:

    <CodeGroup>
      ```bash Node.js Script theme={null}
      envtrap run node app.js
      ```

      ```bash Express / Fastify theme={null}
      envtrap run node server.js
      ```

      ```bash NestJS theme={null}
      envtrap run node dist/main.js
      ```

      ```bash Next.js (Production Server) theme={null}
      envtrap run npm run start
      ```
    </CodeGroup>

    <Note>
      `envtrap` forwards all process arguments, environment variables, exit codes, and signals (`SIGINT`, `SIGTERM`) directly to and from your application.
    </Note>
  </Step>

  <Step title="Review the startup banner">
    When `envtrap` starts, it reads available secrets from `process.env` and your `.env` file, spins up the in-memory MITM proxy, and outputs a configuration overview to standard error:

    ```text theme={null}
      ℹ  [envtrap] Configuration loaded: envtrap.json
      ℹ  [envtrap] Active monitoring channels:
      ℹ  [envtrap]   - stdout: [WARN]
      ℹ  [envtrap]   - stderr: [WARN]
      ℹ  [envtrap]   - network: [BLOCK]
      ℹ  [envtrap]   - child_process: [WARN]
      ℹ  [envtrap]   - dns: [BLOCK]

      ⚠  envtrap v3.0.0
         Monitoring: node app.js
         Channels: stdout/stderr · HTTPS MITM · child_process · DNS hooks
    ```
  </Step>

  <Step title="Simulate or observe an interception">
    If any dependency or script attempts to transmit credentials over an unapproved channel, envtrap immediately intercepts the operation and logs a structured alert box:

    ```text theme={null}
     🌐 SECRET LEAK DETECTED   2026-09-05T14:05:32.203Z
    ────────────────────────────────────────────────────────────
      Secret:  STRIPE_SECRET_KEY  (source: env)
      Value:   [SHA256:56018fa55485...]
      Channel: 🌐  NETWORK
      Context:
        Outbound HTTPS Request Audited:
          Destination Host: attacker.com
          Request Line:     POST /collect
          Headers:
            Authorization: Bearer [REDACTED: SHA256:56018fa5]
    ────────────────────────────────────────────────────────────
      ⚠  [envtrap] Network leak blocked: closing connection to attacker.com
    ```

    <Info>
      Notice that the actual secret value is never printed in plain text. It is automatically replaced with a non-reversible SHA-256 fingerprint prefix, protecting your credentials even if logs are ingested into public CI/CD pipelines or cloud dashboards.
    </Info>
  </Step>

  <Step title="Inspect the exit summary">
    When your application terminates, envtrap prints a grouped summary of all monitored events and writes an incident audit report to `.envtrap-report.json`:

    ```text theme={null}
    ════════════════════════════════════════════════════════════
      envtrap — Run Summary
    ────────────────────────────────────────────────────────────
      🚨  1 leak event(s) detected!

      🌐  NETWORK: 1 leak(s)
           → STRIPE_SECRET_KEY (blocked)
    ════════════════════════════════════════════════════════════
    ```
  </Step>
</Steps>

***

## Adding to `package.json`

To make envtrap a standard part of your development and production lifecycle, wrap your npm scripts in `package.json`:

```json package.json theme={null}
{
  "scripts": {
    "start": "envtrap run node dist/main.js",
    "dev": "envtrap run node --watch src/index.js"
  }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Reference" icon="sliders" href="/docs/configuration/envtrap-json">
    Learn how to configure channel modes, exclude trusted domains, and set custom entropy levels.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/docs/api-reference/endpoint">
    Explore all CLI flags including `--env-file`, `--no-mitm`, `--verbose`, and `--log-file`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.