Configuration reference

Every environment variable and the scoring file that configure the Trace server.

All configuration is through environment variables, validated at startup. Invalid values stop the server with a message naming the variable (never its value).

Server: required

VariableDescription
DATABASE_URLPostgres connection string.
TOKEN_SECRET32+ random characters. Signs visitor tokens, keys IP hashes, encrypts webhook secrets.
AUTH_SECRET32+ random characters, different from TOKEN_SECRET. Signs dashboard sessions.

Server: network and dashboard

VariableDefaultDescription
HOST0.0.0.0Listen address.
PORT8080Listen port.
DASHBOARD_URLhttp://localhost:3000Public URL of the dashboard. Used for sessions and CSRF checks.
DASHBOARD_ALLOW_SIGNUPfalseAllow sign-ups after the first account.
TRUST_PROXYfalsefalse, true, or a comma list of proxy IPs/CIDRs.
REQUEST_TIMEOUT_MS10000Per-request timeout.
REDIS_URLunsetRedis for rate limits and velocity. Optional.
DB_STATEMENT_TIMEOUT_MS5000Postgres statement timeout per connection.
DB_POOL_MAX10Postgres connections per server process.

Server: data and privacy

VariableDefaultDescription
IP_STORAGEtruncatedHow IPs are stored on events: full, truncated (/24, /48), hashed, none.
EVENT_VERIFY_WINDOW_MINUTES60How long GET /v1/events/:id accepts an event.
RETENTION_MAX_DAYS90Upper bound for any project's retention; whole partitions older than this are dropped.
MAINTENANCE_INTERVAL_MINUTES360How often retention and partition upkeep run.
CROSS_BROWSER_LINKINGtrueLink visitors that look like one device in different browsers (linkedVisitors, crossBrowser signal). Always off when IP_STORAGE=none. See privacy.
SEALED_RESULTS_KEYunsetBase64 of 32 random bytes (openssl rand -base64 32). Identify responses then carry sealedResult, the full event encrypted with AES-256-GCM, for your backend to open with unsealEventResult (sdk-node). Keep it as secret as the secret key.
SCORING_CONFIG_PATHbundled scoring.default.jsonReplace weights and thresholds with your own file.

Server: IP intelligence

IP facts (country, ASN, location, Tor, VPN, proxy, datacenter, relay, blocklisted) come from local files, from IP data providers, or both. Files cost nothing per request and keep visitor IPs on your server; npm run ip-data -w trace-server -- <dir> downloads free ones (see Self-hosting: IP data). Changed files are reloaded within 10 minutes, without a restart.

Local files

VariableDescription
TOR_EXIT_LIST_FILETor exit IPs, one per line.
DATACENTER_CIDR_FILEHosting/cloud ranges, one IP or CIDR per line.
IP_BLOCKLIST_FILEYour blocklist, one IP or CIDR per line.
GEOIP_COUNTRY_DBMaxMind-format Country or City .mmdb.
GEOIP_ASN_DBMaxMind-format ASN .mmdb.
DATACENTER_ASN_FILEHosting ASNs, one per line (needs GEOIP_ASN_DB).
RELAY_CIDR_FILEPrivacy-relay egress ranges, reported in vpn details. Apple publishes iCloud Private Relay's as CSV (egress-ip-ranges.csv); only the first column is read.
VPN_CIDR_FILECommercial VPN exit ranges, one IP or CIDR per line (vpn method publicVpn).
VPN_ASN_FILEVPN provider ASNs, one per line (needs GEOIP_ASN_DB).
CRAWLER_RANGES_FILEPublished IP ranges of crawlers and AI agents, as JSON (crawler name to CIDR list), written by npm run crawler-ranges -w trace-server -- <file>. Refresh it daily; the server re-reads the file when it changes (checked every 10 minutes). Unset: only search engines are verified, by reverse DNS.
PROXY_CIDR_FILEResidential and datacenter proxy exit ranges, one IP or CIDR per line. Unset: proxy is unavailable.

IP data providers

Name providers in IP_PROVIDERS (comma separated, highest priority first) and set their keys. They run in parallel within one time budget per identify, after which a slow provider's fields read "not checked" for that event; a failing provider never fails an identification and is logged at most once a minute. Answers are cached per IP. Private and reserved addresses are never sent. The local files below are always consulted too, after the providers. For country, ASN and location the first source that answers wins; a flag (VPN, proxy, Tor, datacenter, relay, blocklisted) is set when any source reports it.

VariableDefaultDescription
IP_PROVIDERSunsete.g. ipqualityscore,ipinfo. Unknown names or missing keys stop the server at startup with the variable named.
IP_PROVIDER_TIMEOUT_MS400Budget for all provider lookups of one identify.
IP_PROVIDER_CACHE_HOURS24How long an answer for an IP is reused. 0 turns caching off.
IP_PROVIDERS nameVariablesFills
ipqualityscoreIPQS_KEY, IPQS_STRICTNESS (0 to 3, default 1)Country, ASN, location, VPN (active_vpn), Tor (active_tor), proxy, recent abuse as blocklisted
ipinfoIPINFO_TOKEN, IPINFO_PLAN (core default, or lite)Country and ASN (Lite); location, hosting and one anonymity flag reported as VPN (Core)
maxmindMAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY, MAXMIND_SERVICE (insights default, city, country)Country, ASN, location; VPN, proxy (public and residential), Tor, hosting with Insights
spurSPUR_TOKENCountry, ASN; VPN, proxy (residential and callback proxies), Tor, datacenter
ipdataIPDATA_KEYCountry, ASN, location; VPN (Business plans), Tor, proxy, iCloud relay, datacenter, known attackers as blocklisted
ipapi.isIPAPI_IS_KEYCountry, ASN, location, VPN, Tor, proxy, datacenter, abusers as blocklisted
ip2location.ioIP2LOCATION_IO_KEYCountry, ASN, location, proxy; VPN, Tor, datacenter with the Security plan
ipregistryIPREGISTRY_KEYCountry, ASN, location, VPN, Tor exit, proxy, relay, cloud provider, threats as blocklisted
proxycheckPROXYCHECK_KEY (optional on the free tier)Country, ASN, location, VPN, Tor or other proxy by detected type
abuseipdbABUSEIPDB_KEY, ABUSEIPDB_MIN_SCORE (default 75)Country, Tor, hosting; blocklisted at or above the abuse confidence score
ipgeolocationIPGEOLOCATION_KEY, IPGEOLOCATION_SECURITY=true (paid)Country, ASN, location; VPN, Tor, proxy, cloud, attackers with security
ip-apiIP_API_KEY (pro, HTTPS), or IP_API_ALLOW_FREE_HTTP=trueCountry, ASN, location, proxy, hosting. The free endpoint is HTTP only and not for commercial use.
cdn-headersIP_COUNTRY_HEADER (e.g. cf-ipcountry, x-vercel-ip-country, cloudfront-viewer-country)Country from your CDN, free and instant; Cloudflare's T1 marks Tor. Only when the CDN is the only way in, or anyone can send the header.

Each provider receives the visitor's IP address and nothing else. That makes it a processor of personal data under GDPR and similar laws: have a data processing agreement with it and name it in your privacy policy. The local files below send nothing anywhere.

Other

VariableDescription
AGENT_DIRECTORIESWeb Bot Auth key directories trusted for signed AI agents, comma separated origins. Default https://chatgpt.com. * fetches any https directory a request names; off turns the check off.
TLS_FINGERPRINT_HEADERName of the header a trusted TLS-terminating proxy fills with the JA4 fingerprint (e.g. x-ja4). Unset: tlsMismatch is unavailable.
JA4_BLOCKLIST_FILEKnown bot and scraper JA4 fingerprints, one per line.

Server: rate limits (per minute)

VariableDefault
RATE_LIMIT_INGEST_PER_KEY_PER_MIN1200
RATE_LIMIT_INGEST_PER_IP_PER_MIN60
RATE_LIMIT_INGEST_PER_VISITOR_PER_MIN30
RATE_LIMIT_API_PER_KEY_PER_MIN600 (also used per dashboard user)

Server: webhooks

VariableDefaultDescription
WEBHOOK_TIMEOUT_MS5000Per-attempt timeout.
WEBHOOK_POLL_INTERVAL_MS1000How often the worker looks for due deliveries.
WEBHOOK_ALLOW_INSECUREfalseDevelopment only: allow http:// and private-network targets. Never in production.

Dashboard

VariableDefaultDescription
API_URLhttp://localhost:8080Server address the dashboard forwards /api/auth and /v1 to. Read at request time.
PORT3000Listen port (Docker image).

Docker Compose (docker/.env)

POSTGRES_PASSWORD, TOKEN_SECRET and AUTH_SECRET are required. Optional: POSTGRES_USER, POSTGRES_DB, SERVER_PORT, DASHBOARD_PORT, DASHBOARD_URL, TRUST_PROXY, IP_STORAGE, EVENT_VERIFY_WINDOW_MINUTES.

Scoring file

scoring.default.json holds identification settings (method: linkage by default or weighted; linkage: change rates, prior frequencies, correlated groups and the match probability, see accuracy; weights and thresholds for the weighted method), suspect-score weights per signal, velocity thresholds, the account limits (accounts: windowHours, maxAccountsPerDevice, maxDevicesPerAccount), and the cross-browser linking settings (crossBrowser: trait weights, must-match traits, thresholds, requireSharedNetwork, networkWindowHours; see the signal catalog). Override files written before a section or signal existed still load; the missing parts take their defaults. Copy it, change values, and point SCORING_CONFIG_PATH at the copy; the server validates it at startup and refuses unknown keys. The accuracy harness can evaluate a candidate file: npm run accuracy -w trace-server -- --config /absolute/path/to/file.json.

Edit this page on GitHub

This page is in the public repository: fix it and send a pull request.