Figranium Environment Variables and Configuration

Figranium uses environment variables to configure key aspects of the server and automation environment. These variables are defined in src/server/constants.js.

Core Variables

Ports, sessions, IP restrictions, and proxy trust settings.

Execution

Host-aware concurrency, queueing, and execution timeouts.

Rate Limiting

VNC / Headful

noVNC port for headful browser debugging.

Feature Flags

Session cookie security and other toggles.

Browser Engine

CloakBrowser stealth engine configuration.

CAPTCHA Solving

Remote provider, local model, and Apple companion settings.

PostgreSQL

Postgres connection and SSL options.

Core Variables

Variable	Default Value	Description
`PORT`	`11345`	The port the backend server listens on.
`SESSION_SECRET`	(Required)	A random string used to sign session cookies.
`NODE_ENV`	`production`	Set to `development` for local dev mode.
`ALLOWED_IPS`	`*` (Open)	Comma-separated list of allowed IP addresses or CIDR ranges.
`ALLOW_PRIVATE_NETWORKS`	`false`	Set to `true` or `1` to allow access to local/private networks (SSRF risk).
`TRUST_PROXY`	`false`	Set to `true` or `1` if running behind a reverse proxy (e.g., Nginx, AWS ALB). Automatically enabled when `RENDER=true`.

Execution

Variable	Default Value	Description
`MAX_CONCURRENT_EXECUTIONS`	host-aware	Override the automatic limit on how many browser executions run at once.
`MAX_EXECUTION_QUEUE`	`50`	Maximum number of executions that can wait for capacity. New work beyond this receives `503`.
`EXECUTION_QUEUE_TIMEOUT_MS`	`600000` (10 min)	Maximum time an execution can wait in the queue before it is rejected.
`EXECUTION_TIMEOUT_MS`	`900000` (15 min)	Maximum runtime for a non-headful execution. Runs that exceed it are stopped and return `504 EXECUTION_TIMEOUT`.
`RESOURCE_MEMORY_RESERVE_MB`	max(512 MB, 15% of memory)	Minimum memory headroom kept free for the host.
`RESOURCE_CPU_THRESHOLD`	`0.9`	Normalized CPU load (load average divided by CPU count) at which Figranium pauses dequeuing.
`RESOURCE_PROBE_INTERVAL_MS`	`30000`	How often runtime resource protection samples memory and CPU.

Host-aware resource protection

Starting in v0.19, Figranium protects the host from running too many Chromium processes at once. It reads available memory (including Docker cgroup limits) and CPU count, then picks a conservative concurrency limit automatically:

Available memory	Automatic concurrency
2.5 GB or less	1
Under 6 GB	2 (or the CPU count, if lower)
6 GB or more	Up to 4, bounded by CPU count minus one and the memory left after the reserve (about 768 MB per execution)

Executions beyond the limit wait in a first-in, first-out queue. When free memory drops below the reserve or CPU load reaches RESOURCE_CPU_THRESHOLD, the queue pauses until pressure eases. If the queue is full or an execution waits longer than EXECUTION_QUEUE_TIMEOUT_MS, the request returns 503 with RESOURCE_CAPACITY_EXCEEDED and a Retry-After header. On shutdown, queued executions are released cleanly. Set MAX_CONCURRENT_EXECUTIONS to a positive integer to replace the automatic limit. You can check the current limit, pressure, and queue length from GET /api/health. For an in-depth explanation and tuning examples, see Resource Protection.

Rate Limiting

Variable	Default Value	Description
`AUTH_RATE_LIMIT_MAX`	`10`	Max failed login attempts per window (15 mins).
`DATA_RATE_LIMIT_MAX`	`100`	Max data requests (captures, logs) per window (15 mins).

VNC / Headful Debugging

Variable	Default Value	Description
`NOVNC_PORT`	`54311`	Port for the noVNC web interface.

Feature Flags

Variable	Default Value	Description
`SESSION_COOKIE_SECURE`	`false`	Set to `true` if serving over HTTPS.
`FIGRANIUM_TELEMETRY_ENABLED`	`true`	Controls anonymous usage telemetry. Set to `false` to disable telemetry entirely.
`PASSWORD_CACHE_ENABLED`	`true`	Controls server-side caching of 1Password Login-item metadata and password lookups. Set to `false` to bypass the cache.
`PASSWORD_CACHE_KEY`	Local key file	Optional secret used to derive the encryption key for the 1Password cache. If unset, Figranium creates or reuses `data/password_cache.key`.
`MASTER_KEY`	—	Optional external master key that enables authenticated encryption for new file-backed secrets. Without it, new file-backed secret writes use plaintext JSON.
`MASTER_KEY_FILE`	`data/master.key`	Optional path for the local master-key file used when configured. Use a persistent, separately protected path for stronger key separation.

By default, Figranium caches 1Password Login-item metadata and password lookups on the server to reduce repeated requests. The persistent cache is encrypted with AES-256-GCM. If PASSWORD_CACHE_KEY is unset, Figranium creates or reuses a random key in data/password_cache.key; the cache file and key are stored together in data/ by default. For more control, set PASSWORD_CACHE_KEY to a secret managed separately from that directory. Secret encryption is opt-in for new file-backed credentials. Configure MASTER_KEY to enable authenticated envelope encryption, and use MASTER_KEY_FILE when you need to control the local key-file path. Without an explicitly configured master key, new file-backed secret writes use plaintext JSON. Existing encrypted files remain accessible with their original key and migrate to plaintext only after successful decryption when encryption is disabled. Figranium refuses to overwrite encrypted data when its original key is unavailable. Set PASSWORD_CACHE_ENABLED=false in your environment or Docker Compose environment section to bypass the cache and retrieve values directly from 1Password. Password management can continue if the optional encrypted local cache cannot be written. See Passwords for file protection and cache expiry details.

Browser Engine

Variable	Default Value	Description
`USE_CLOAK_ENGINE`	`false`	Set to `true` (or `1`) to run the browser engine on CloakBrowser, a stealth-patched Chromium binary, instead of the default Playwright + `puppeteer-extra-plugin-stealth` stack. Applies to Agent and Headful runners.
`CLOAKBROWSER_LICENSE_KEY`	—	CloakBrowser license key for the latest stealth binary. Read natively by cloakbrowser; you can also run `npx cloakbrowser login` to write it to `~/.cloakbrowser/license.key`. Without a key, the free legacy binary is used.

See Stealth & Anti-Detection for when to switch engines and what the CloakBrowser stack changes.

CAPTCHA Solving

Variable	Default Value	Description
`CAPTCHA_SOLVER_URL`	—	Optional YesCaptcha/AntiCaptcha-compatible endpoint. When set, remote solving is attempted first, then falls back to the built-in local model.
`CAPTCHA_SOLVER_KEY`	—	Client key for `CAPTCHA_SOLVER_URL`.
`CAPTCHA_MODEL_TIER`	`auto`	Local model selection: `auto`, `owlvit`, or `florence2`. `auto` selects OWL-ViT on 2–7.99 GiB hosts and Florence-2 at 8 GiB+.
`CAPTCHA_MODEL_DEVICE`	`auto`	Local inference device policy: `auto` or `cpu`.
`SKIP_LOCAL_CAPTCHA_MODEL`	`false`	Disable local model detection, download, startup, reconciliation, and fallback. Cached weights are retained.
`CAPTCHA_AUTO_DETECT_TIMEOUT_MS`	`5000`	How long each Auto-Solve Captchas pass waits for a challenge to become ready before moving on.
`CAPTCHA_REMOTE_TIMEOUT_MS`	action deadline minus local reserve	Maximum time allocated to the remote route before falling back locally.
`CAPTCHA_LOCAL_FALLBACK_MIN_MS`	`15000`	Portion of the action deadline reserved for the active-browser local route.
`CAPTCHA_REMOTE_FORWARD_PROXY`	`false`	Opt in to sending the active browser proxy and user agent to compatible proxy-backed remote tasks.
`CAPTCHA_REMOTE_FORWARD_CONTEXT`	`false`	Opt in to sending origin-scoped cookies, locale, timezone, viewport, and user agent to a custom endpoint advertising `browserContext` version 1.
`CAPTCHA_OWLVIT_THRESHOLD` / `CAPTCHA_FLORENCE2_THRESHOLD`	`0.12` / `0.18`	Optional tier-specific confidence overrides in the range 0–1.
`CAPTCHA_COMPANION_URL`	auto-detected	Optional Apple Silicon companion URL. Docker Desktop discovers `http://host.docker.internal:11438`; native macOS uses loopback.
`CAPTCHA_COMPANION_TOKEN`	generated file	Bearer token for the Apple companion. If omitted, `data/captcha-companion-token` is used.
`OHMYCAPTCHA_URL` / `OHMYCAPTCHA_CLIENT_KEY`	—	Deprecated aliases for `CAPTCHA_SOLVER_URL` / `CAPTCHA_SOLVER_KEY`.

See CAPTCHA Solving for the full feature reference, including the task-level auto-solve toggle and troubleshooting.

Database (PostgreSQL)

Variable	Default Value	Description
`DB_TYPE`	`json`	Set to `postgres` to enable PostgreSQL backend storage.
`DB_POSTGRESDB_HOST`	—	Hostname of your PostgreSQL database server.
`DB_POSTGRESDB_PORT`	`5432`	Port of your PostgreSQL server.
`DB_POSTGRESDB_USER`	—	Database username.
`DB_POSTGRESDB_PASSWORD`	—	Database password.
`DB_POSTGRESDB_DATABASE`	—	Database name.
`DB_POSTGRESDB_SSL`	`false`	Set to `true` to enable SSL/TLS database connections.

Figranium also accepts the shorter DB_PROTOCOL, DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE, and DB_SSL names, plus their lowercase forms (for example, db_host). PostgreSQL connection details can only be set with environment variables, not from the Settings page. See Alternative variable names.

For production deployments, Neon is the recommended backend database provider due to its serverless autoscaling and zero-maintenance PostgreSQL infrastructure. See PostgreSQL Support for full details.

Example `.env` File

PORT=11345
SESSION_SECRET=super_secret_key_12345
ALLOWED_IPS=127.0.0.1,192.168.1.0/24
ALLOW_PRIVATE_NETWORKS=false
TRUST_PROXY=true
AUTH_RATE_LIMIT_MAX=20
DATA_RATE_LIMIT_MAX=500
NOVNC_PORT=54311
SESSION_COOKIE_SECURE=true

# Optional: override automatic resource protection
MAX_CONCURRENT_EXECUTIONS=3
EXECUTION_TIMEOUT_MS=900000

# Optional PostgreSQL configuration (Recommended: Neon)
DB_TYPE=postgres
DB_POSTGRESDB_HOST=ep-example-123456.us-east-2.aws.neon.tech
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_USER=figranium_owner
DB_POSTGRESDB_PASSWORD=your_neon_password
DB_POSTGRESDB_DATABASE=neondb
DB_POSTGRESDB_SSL=true

# Optional CloakBrowser engine
USE_CLOAK_ENGINE=true
CLOAKBROWSER_LICENSE_KEY=your_cloakbrowser_license_key

# Optional CAPTCHA solving (remote endpoint; local model runs by default)
CAPTCHA_SOLVER_URL=https://solver.example.com
CAPTCHA_SOLVER_KEY=your-client-key

Notes

Allow Private Networks: By default, ALLOW_PRIVATE_NETWORKS is false, meaning Figranium blocks requests to private and internal network addresses. If you need to scrape services on your local network (e.g., during development), set this to true.
Session Secret: If SESSION_SECRET is not provided, Figranium will generate a random one on startup (or read from data/session_secret.txt if available). However, for consistent sessions across restarts, set a static secret.
Allowed IPs: If you expose Figranium to the internet, always restrict access using ALLOWED_IPS or authentication.

Introduction

Get Started

Editor & Task Building

Data & Extraction

Running Tasks

Anti-Detection

Templates

Operations

Figranium Environment Variables and Configuration

Core Variables

Execution

Rate Limiting

VNC / Headful

Feature Flags

Browser Engine

CAPTCHA Solving

PostgreSQL

Core Variables

Execution

Host-aware resource protection

Rate Limiting

VNC / Headful Debugging

Feature Flags

Browser Engine

CAPTCHA Solving

Database (PostgreSQL)

Example `.env` File

Notes

Core Variables

Execution

Rate Limiting

VNC / Headful

Feature Flags

Browser Engine

CAPTCHA Solving

PostgreSQL

​Core Variables

​Execution

​Host-aware resource protection

​Rate Limiting

​VNC / Headful Debugging

​Feature Flags

​Browser Engine

​CAPTCHA Solving

​Database (PostgreSQL)

​Example .env File

​Notes

Core Variables

Execution

Host-aware resource protection

Rate Limiting

VNC / Headful Debugging

Feature Flags

Browser Engine

CAPTCHA Solving

Database (PostgreSQL)

Example `.env` File

Notes