Configuration
Runtime environment variables, dashboard settings, and config API behavior
by saifyxpro
HeadlessX configuration now comes from three layers:
- Required environment variables for booting the stack
- Optional environment defaults that seed or influence runtime behavior
- Dashboard / API-managed settings stored in the database
Required environment variables
These values are part of the current working setup and should be present in .env.
| Variable | Required | Purpose |
|---|---|---|
DATABASE_URL | Yes | PostgreSQL connection string for Prisma and application state |
PORT | Yes | Backend API port |
WEB_PORT | Yes for local clarity | Frontend dashboard port |
NEXT_PUBLIC_API_URL | Yes | URL the dashboard uses to reach the backend |
FRONTEND_URL | Yes for non-default deploys | Allowed frontend origin for CORS |
DASHBOARD_INTERNAL_API_KEY | Yes | Shared secret used by the Next.js dashboard server when proxying /api/* |
CREDENTIAL_ENCRYPTION_KEY | Yes | Key used to encrypt stored proxy and profile passwords |
Example
Optional environment-backed settings
These are still read by the backend today, but they are better treated as defaults than as your main operating interface.
| Variable | Default | Notes |
|---|---|---|
NODE_ENV | development | Standard runtime mode |
HOST | 0.0.0.0 | Host binding for deployment scenarios |
BROWSER_HEADLESS | true | Default browser headless mode before dashboard overrides are saved |
BROWSER_TIMEOUT | 60000 | Default browser timeout in milliseconds |
MAX_CONCURRENCY | 5 | Default concurrency before dashboard settings take over |
PROFILE_ROTATION_ENABLED | false | Default profile rotation toggle |
PROFILE_ROTATION_INTERVAL | 3600000 | Default profile rotation interval in milliseconds |
BODY_LIMIT | 10mb | Express JSON body size limit |
Some variables still present in older docs or examples are not wired into the current runtime. This page only documents values that are reflected in the codebase today.
Dashboard-managed settings
The dashboard and config API persist the main runtime settings to the database. The current ConfigController supports these fields:
| Setting | Type | Meaning |
|---|---|---|
browserHeadless | boolean | Run the browser without a visible UI |
browserTimeout | number | Request/browser timeout in milliseconds |
maxConcurrency | number | Maximum concurrent scraping jobs |
profileRotationInterval | number | Rotation interval for profile reuse workflows |
camoufoxGeoip | boolean | Let Camoufox align location with proxy IP |
camoufoxBlockWebrtc | boolean | Disable WebRTC leakage paths |
camoufoxBlockImages | boolean | Skip image loading when you want lighter pages |
camoufoxEnableCache | boolean | Enable browser caching |
camoufoxHumanize | number | Humanization factor used by the browser stack |
Important behavior
- Environment values act as defaults when the settings table is empty
- Once settings are stored in the database, they become the active source of truth
- Updating config through the API invalidates the backend config cache and restarts the browser service
Config API
All config endpoints require X-API-Key.
Get config
Example response shape:
Update config
Profiles and proxies
Profiles and proxies are configured through their own API groups and dashboard pages:
- Profiles:
/api/profiles - Proxies:
/api/proxies
Those routes now require API key auth and no longer return raw stored passwords.
Security notes
Dashboard auth model
The dashboard is not meant to expose an internal secret in browser code anymore. The current model is:
- Browser talks to Next.js
/api/* - Next.js server injects
DASHBOARD_INTERNAL_API_KEY - Backend verifies that internal secret or a normal API key
External integrations
For curl, n8n, Make, Zapier, or custom apps, call the backend directly and send a normal API key in X-API-Key.
Troubleshooting
Config changes do not seem to apply
Check these in order:
- Confirm the request returned
success: true - Re-fetch
/api/configto verify the saved value - If you changed
.env, restart the affected process - If you changed security variables, restart both API and dashboard
Dashboard and API disagree
Make sure the dashboard is pointing at the same backend you are testing:
NEXT_PUBLIC_API_URLFRONTEND_URLPORTWEB_PORT