> ## Documentation Index
> Fetch the complete documentation index at: https://envtrap.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get envtrap v2.1 protecting your Node.js app in under 60 seconds.
## Prerequisites
* Node.js **18.0.0 or later** (ESM customization hooks require Node 18+)
* npm or pnpm
## Step 1 — Install
Install `envtrap` globally:
```bash theme={null}
npm install -g envtrap
```
Or use via npx without installing:
```bash theme={null}
npx envtrap run node app.js
```
Or install as a dev dependency:
```bash theme={null}
npm install --save-dev envtrap
```
## Step 2 — Run your app through envtrap
Prefix your existing start command with `envtrap run`:
```bash theme={null}
# Before
node app.js
# After — fully monitored
envtrap run node app.js
```
That's it. envtrap now:
* Starts a native-RSA in-memory MITM TLS proxy and routes all outbound HTTP/HTTPS through it
* Automatically sets `NO_PROXY` for loopback addresses so local Redis, Docker, and sidecar services are never proxied
* Scans stdout and stderr streams for secrets in real time
* Intercepts all `child_process` spawns to check if secrets are passed via `options.env`
* Intercepts all DNS lookups for exact secret matches and high-entropy subdomain patterns
* Wraps `process.env` to detect and broadcast runtime-rotated credentials to the ESM loader thread
## Step 3 — Read the startup output
On every run, envtrap prints a startup banner and configuration summary to stderr:
```
ℹ [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 v2.1.0
Monitoring: node app.js
Channels: stdout/stderr · HTTPS MITM · child_process · ESM hooks
```
When a leak is detected:
```
🌐 SECRET LEAK DETECTED 2026-06-29T14: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
```
After your app exits, envtrap prints a summary:
```
════════════════════════════════════════════════════════════
envtrap — Run Summary
────────────────────────────────────────────────────────────
🚨 1 leak event(s) detected!
🌐 NETWORK: 1 leak(s)
→ STRIPE_SECRET_KEY
════════════════════════════════════════════════════════════
```
## Step 4 — (Optional) Create a config file
Create `envtrap.json` in your project root for fine-grained control:
```json theme={null}
{
"channels": {
"stdout": "warn",
"stderr": "warn",
"network": "block",
"child_process": "warn",
"dns": "block"
},
"exclusions": {
"domains": ["api.stripe.com", "api.openai.com"],
"paths": ["test/**"]
},
"entropy": {
"threshold": 3.5,
"minLength": 12
},
"quiet": false,
"logFile": "logs/envtrap.jsonl"
}
```
Domains listed in `exclusions.domains` are automatically added to `NO_PROXY` so they also bypass the MITM proxy without any extra configuration.
Validate your config:
```bash theme={null}
envtrap check
```
Use `"warn"` on all channels during development to observe traffic patterns. Switch `network` and `dns` to `"block"` before deploying to production.
## Step 5 — Add to package.json scripts
```json theme={null}
{
"scripts": {
"start": "envtrap run node app.js",
"dev": "envtrap run node --watch app.js"
}
}
```
## What Happens on Detection?
| Channel | `"warn"` mode | `"block"` mode |
| --------------- | ------------------------------------------ | --------------------------------------------------- |
| `network` | Leak logged, request forwarded | Leak logged, connection terminated (socket destroy) |
| `stdout` | Secret redacted in output, child continues | Child process killed via `SIGTERM` |
| `stderr` | Secret redacted in output, child continues | Child process killed via `SIGTERM` |
| `child_process` | Leak logged via stderr, spawn proceeds | Synchronous `Error` thrown, no OS fork |
| `dns` | Leak logged, lookup proceeds | Synchronous `Error` thrown, no DNS packet sent |
## Framework Compatibility
envtrap hooks Node.js core modules, not your application layer — so it works with any framework:
| Framework | Command |
| ----------------- | ------------------------------- |
| Express / Fastify | `envtrap run node server.js` |
| NestJS | `envtrap run node dist/main.js` |
| Next.js (server) | `envtrap run npm run start` |
| Bare Node.js | `envtrap run node script.js` |
Next.js and other frameworks that compile or bundle client-side code are covered only for server-side execution. Browser runtime code is not in scope.
## Next Steps
Deep-dive into MITM proxy, ESM hooks, and CJS patching.
Full reference for every envtrap.json field.
Understand the five channels envtrap monitors.
All CLI commands and flags.