diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..ceac8c3
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,15 @@
+# AgentPay backend local configuration.
+# Copy this file to `.env` for local overrides. Do not commit real secrets.
+
+# HTTP listen port for npm run dev / npm start.
+# Default in src/index.ts: 3001
+PORT=3001
+
+# Comma-separated browser origins allowed by the CORS middleware.
+# Empty means no Access-Control-Allow-Origin header is emitted.
+# Example: CORS_ALLOWED_ORIGINS=http://localhost:3000,https://dashboard.example.com
+CORS_ALLOWED_ORIGINS=
+
+# Runtime mode. Use `test` only for automated tests; it disables the in-process
+# rate limiter and suppresses per-request JSON logs.
+NODE_ENV=development
diff --git a/.gitignore b/.gitignore
index ae41fb7..4e8d93e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,5 +2,6 @@ node_modules
 dist
 .env
 .env.*
+!.env.example
 *.log
 .DS_Store
diff --git a/README.md b/README.md
index 337ee4f..9f2fd52 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,19 @@ API gateway, metering, and billing backend for the AgentPay protocol (machine-to
    ```
    Server runs at `http://localhost:3001`. Try `GET /health` and `GET /api/v1/version`.
 
+## Configuration
+
+The backend reads these environment variables at runtime. For local development,
+copy [`.env.example`](.env.example) to `.env` and adjust values as needed. The
+real `.env` files stay ignored by git; `.env.example` contains only safe
+placeholders.
+
+| Variable | Default | Purpose |
+| -------- | ------- | ------- |
+| `PORT` | `3001` | HTTP listen port used by `src/index.ts` when the server starts. |
+| `CORS_ALLOWED_ORIGINS` | empty | Comma-separated allowlist for browser CORS origins. When empty, the backend does not emit `Access-Control-Allow-Origin`; when an incoming `Origin` exactly matches an entry, the middleware echoes that origin and related CORS headers. |
+| `NODE_ENV` | unset | Runtime mode. Set to `test` only for automated tests; in test mode the in-process rate limiter is skipped and per-request JSON logs are suppressed. |
+
 ## Project structure
 
 ```