Configuration

Nginjen uses TOML for configuration. The config file is optional; all settings have sensible defaults.

Config File Location

Nginjen looks for config.toml in this order:

1. Path passed via --config flag
2. ~/.config/nginjen/config.toml (Linux/macOS)
3. Built-in defaults

Full Example

[engine]
type = "chromium"            # "chromium" (recommended)
path = "auto"                # "auto" = download, or "/path/to/chrome"
# proxy = "socks5://127.0.0.1:1080"  # Global proxy for all sessions

[server]
host = "127.0.0.1"
port = 9090
request_timeout_secs = 30    # Per-request timeout
max_concurrent_pages = 5     # Max parallel browser pages

[stealth]
headless_mode = "new"        # "new", "shell" (Chrome 131+), "virtual-display" (Xvfb)
headless = true              # Legacy alias for headless_mode
args = [
    "--no-sandbox",
    "--disable-blink-features=AutomationControlled",
    "--disable-features=IsolateOrigins,site-per-process",
    "--disable-site-isolation-trials",
]

[log]
level = "info"               # trace, debug, info, warn, error

[search]
backend = "lite"             # "lite" (DuckDuckGo), "bing", "brave", "meta", "searxng"
# searxng_url = "http://localhost:8080"  # Only for searxng backend

Engine

Key	Default	Description
type	"chromium"	Engine type. chromium is recommended. Deprecated aliases resolve to chromium.
path	"auto"	"auto" downloads Chromium automatically. Or set to a specific binary path.
proxy	(none)	Global proxy URL for all sessions. Format: socks5://host:port, http://host:port

Server

Key	Default	Description
host	"127.0.0.1"	Bind address
port	9090	HTTP API port
request_timeout_secs	30	Per-request timeout in seconds
max_concurrent_pages	5	Maximum parallel browser pages (semaphore)

Stealth

Key	Default	Description
headless_mode	"new"	Headless strategy. See below.
headless	true	Legacy alias. Maps to headless_mode.
args	(see above)	Extra Chromium command-line flags

Headless Modes

Mode	Description	Stealth Strength
"new"	Chrome's new headless mode (default)	Good
"shell"	Chrome 131+ headless shell	Better
"virtual-display"	Xvfb virtual framebuffer (strongest)	Best

The virtual-display mode requires Xvfb installed on the system. It runs a real browser instance inside a virtual display, making headless detection nearly impossible.

API Authentication

To protect your API server, set an API key:

[api]
api_key = "your-secret-key"

When set, all endpoints except /health, /openapi.json, and /ws require authentication:

curl -H "Authorization: Bearer your-secret-key" http://127.0.0.1:9090/sessions

Leave api_key unset to disable authentication (default).

Search

Key	Default	Description
backend	"lite"	Search backend: lite, bing, brave, meta, searxng
searxng_url	(none)	SearXNG instance URL (only for searxng backend)

Environment Variables

Config values can be overridden via environment variables with the NGINJEN_ prefix:

NGINJEN_SERVER_PORT=8080 nginjen serve