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

Concurrency limits and task queue behavior.

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 companionRemote endpoint and local model solver 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`	(unlimited)	Maximum number of tasks that can run simultaneously. Excess requests are queued until a slot is available.

When set, Figranium queues incoming execution requests that exceed the limit and processes them in order as slots free up. Leave unset (or set to 0) for unlimited concurrency. This is the default and matches the behavior of earlier versions. This is useful when running on resource-constrained hosts or when you want to prevent a burst of scheduled tasks from overwhelming the browser pool.

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.

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.

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
MAX_CONCURRENT_EXECUTIONS=3

# 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.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

Figranium Environment Variables and Configuration

Core Variables

Execution

Rate Limiting

VNC / Headful

Feature Flags

Browser Engine

CAPTCHA Solving

PostgreSQL

Core Variables

Execution

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

​Rate Limiting

​VNC / Headful Debugging

​Feature Flags

​Browser Engine

​CAPTCHA Solving

​Database (PostgreSQL)

​Example .env File

​Notes

Core Variables

Execution

Rate Limiting

VNC / Headful Debugging

Feature Flags

Browser Engine

CAPTCHA Solving

Database (PostgreSQL)

Example `.env` File

Notes