HitKeep Flags and Environment Variables

HitKeep follows the 12-factor app methodology. You can configure the application using either command-line flags or environment variables.

Flags take precedence over environment variables.

For citable runtime facts, including binary size, memory use, storage boundaries, exports, and MCP limits, see Facts and Limits.

Flag name compatibility: Several older flag names still work but are deprecated. The generated tables label each deprecated spelling beside its replacement.

The tables on this page are rendered from the configuration catalog attached to the latest stable HitKeep release. Names, defaults, descriptions, sensitivity, deprecations, and cloud scope come from the same annotations the runtime uses to load configuration.

General Settings

These are the most critical settings to get HitKeep running correctly.

Flag	Environment variable	Default	Description
--auth-remember-me-days	HITKEEP_AUTH_REMEMBER_ME_DAYS	30	Remember-me session lifetime in days
--auth-session-minutes	HITKEEP_AUTH_SESSION_MINUTES	15	Authenticated dashboard session lifetime in minutes
--auth-session-warning-seconds	HITKEEP_AUTH_SESSION_WARNING_SECONDS	120	Seconds before session expiry to warn users
--healthcheck	N/A	false	Run as healthcheck client
--http-addrDeprecated: -http	HITKEEP_HTTP_ADDR	:8080	HTTP listen address
--jwt-secret	HITKEEP_JWT_SECRET	randomly generated	Secret key for JWTSensitive value; redacted in safe configuration output.
--log-level	HITKEEP_LOG_LEVEL	info	Log level (debug/info/warn/error)
--public-url	HITKEEP_PUBLIC_URL	http://localhost:8080	Public URL

Public URL path prefixes

Use a bare origin when HitKeep owns a hostname:

HITKEEP_PUBLIC_URL=https://analytics.example.com

Use a path-prefixed URL when your reverse proxy mounts HitKeep below another site:

HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/

With a path prefix, HitKeep serves the dashboard shell with <base href="/hitkeep/" />, accepts dashboard API requests below /hitkeep/api/..., and serves tracker files below /hitkeep/hk.js and /hitkeep/hk-vitals.js. The tracker derives /ingest, /ingest/event, and /ingest/web-vitals from the script URL, so a snippet loaded from /hitkeep/hk.js posts back to /hitkeep/ingest. Root /api/..., /hk.js, and dashboard routes are not public fallback routes in this mode. Local /healthz and /readyz remain available for process, container, and Kubernetes checks.

Keep the reverse proxy prefix and HITKEEP_PUBLIC_URL in sync. A mismatch usually appears as a login page that loads but cannot call /api/status, or as a tracker snippet that loads from one path and posts pageviews to another.

Custom tracking domains

Custom tracking domains use the same dashboard flow on HitKeep Cloud and self-hosted installs. Teams add domains in Team Settings, prove ownership with a TXT record, point DNS at an allowed target, and use Site Settings to generate tracking snippets from the instance URL or any active team domain. See Custom Tracking Domains for the full flow.

Flag	Environment variable	Default	Description
--caddy-tls-ask-token	HITKEEP_CADDY_TLS_ASK_TOKEN	""	Bearer-free path token for Caddy on-demand TLS ask endpointSensitive value; redacted in safe configuration output.
--custom-tracking-dns-target	HITKEEP_CUSTOM_TRACKING_DNS_TARGET	""	DNS host or IP custom tracking domains must point at; defaults to public URL host
--custom-tracking-tls-mode	HITKEEP_CUSTOM_TRACKING_TLS_MODE	external	TLS mode for custom tracking domains: external or caddy-on-demand

When HITKEEP_CUSTOM_TRACKING_TLS_MODE=caddy-on-demand, configure Caddy with an ask URL that includes the token. HitKeep returns 204 only for enabled DNS-verified custom tracking domains, so arbitrary hostnames cannot request certificates through your Caddy instance.

Data Management

Flag	Environment variable	Default	Description
--archive-path	HITKEEP_ARCHIVE_PATH	archive	Data archive path
--data-path	HITKEEP_DATA_PATH	data	Local writable base directory for per-tenant database files
--data-retention-daysDeprecated: -retention-days	HITKEEP_DATA_RETENTION_DAYS	365	Default data retention in days
--db-auto-recover	HITKEEP_DB_AUTO_RECOVER	true	Automatically recover recognized DuckDB non-unique index invalidations after creating a local recovery bundle
--db-auto-recover-wal	HITKEEP_DB_AUTO_RECOVER_WAL	false	After retaining a recovery bundle, automatically bypass a recognized non-migration WAL and accept loss of WAL-only changes
--db-checkpoint-interval	HITKEEP_DB_CHECKPOINT_INTERVAL	5	Minutes between periodic DuckDB checkpoints; 0 disables periodic checkpoints
--db-compact-on-start	HITKEEP_DB_COMPACT_ON_START	true	Rewrite fragmented database files on startup and tenant open to return space freed by retention and deletes to the operating system
--db-pathDeprecated: -db	HITKEEP_DB_PATH	hitkeep.db	Database file path
--db-recovery-path	HITKEEP_DB_RECOVERY_PATH	<data-path>/recovery	Directory for permission-restricted DuckDB recovery bundles; defaults to <data-path>/recovery
--duckdb-memory-limit	HITKEEP_DUCKDB_MEMORY_LIMIT	derived	DuckDB memory limit per database (e.g. 2GB); empty derives a container-aware default, 'none' keeps the DuckDB default of 80% of system RAM
--duckdb-threads	HITKEEP_DUCKDB_THREADS	GOMAXPROCS	DuckDB threads per database; 0 derives the default from GOMAXPROCS
--import-max-stage-bytes	HITKEEP_IMPORT_MAX_STAGE_BYTES	107374182400	Maximum staged import upload size in bytes
--import-stage-retention-days	HITKEEP_IMPORT_STAGE_RETENTION_DAYS	7	Days to keep stale staged import upload files; 0 disables import staging cleanup

HITKEEP_DB_PATH is the local SQLite control database. HITKEEP_DATA_PATH holds the local tenant DuckDB files and must also be writable. S3 is supported for HITKEEP_BACKUP_PATH and retention archives, not for live database files. In 2.13 HitKeep first moves default-tenant analytics to {data-path}/tenants/{default-tenant-id}/hitkeep.db, then converts the compact control database to SQLite; there is no opt-out flag. The verified former DuckDB control file is retained as <db-path>.pre-sqlite-2.13.0. Keep a complete pre-upgrade backup because downgrading to 2.12 or older is unsupported.

Tuning memory usage

Tenant analytics use one shared DuckDB instance rooted at the default tenant file. All attached tenant catalogs share its buffer pool, memory limit, thread setting, and global connection gate. The pure-Go SQLite control pool is separately bounded. HitKeep derives a container-aware tenant DuckDB limit automatically; explicit values follow one rule of thumb:

# Rule of thumb: about twice the largest actively queried tenant database.
HITKEEP_DUCKDB_MEMORY_LIMIT=2GB

Do not set the limit far below your database size: DuckDB spills query intermediates to disk, but writes need real memory headroom, and an overly tight limit causes query failures under concurrent load. Reducing HITKEEP_DUCKDB_THREADS lowers peak query memory and lets a given limit go further.

See Performance and Memory for the full picture, including the derived defaults and the DuckDB memory breakdown in System Status → Storage.

Spam Filtering

HitKeep can use a local spam-filter cache for known referrer spam and abuse networks. Automatic refresh is off by default for offline and airgapped installs.

Flag	Environment variable	Default	Description
--spam-filter-auto-update	HITKEEP_SPAM_FILTER_AUTO_UPDATE	false	Automatically refresh OSS spam filter feeds on the leader node (disabled by default for airgapped/offline installs)
--spam-filter-path	HITKEEP_SPAM_FILTER_PATH	""	Path to cached spam filter data (defaults to <data-path>/spam-filter.json)
--spam-filter-update-interval	HITKEEP_SPAM_FILTER_UPDATE_INTERVAL	1440	Minutes between OSS spam filter feed refreshes

See Bot and Spam Filtering for update commands and operator guidance.

Database Backups

HitKeep can periodically export all live databases (shared + per-tenant) to Parquet snapshots. Set HITKEEP_BACKUP_PATH to enable.

Flag	Environment variable	Default	Description
--backup-interval	HITKEEP_BACKUP_INTERVAL	60	Minutes between backups
--backup-path	HITKEEP_BACKUP_PATH	""	Backup snapshot destination (local directory or s3://); live databases remain on the local data path
--backup-retention	HITKEEP_BACKUP_RETENTION	24	Number of backup snapshots to keep

When HITKEEP_BACKUP_PATH is an s3:// URL, the same S3 credentials configured below are used. For local paths, old snapshots beyond the retention count are automatically deleted. For S3, configure lifecycle policies on your bucket.

See Backups and Restore and S3 Backups for concrete layouts and restore examples.

S3 Archive Storage

When HITKEEP_ARCHIVE_PATH is set to an s3:// URL, HitKeep writes Parquet archives directly to S3-compatible storage via DuckDB’s httpfs extension.

Authentication mode is auto-detected:

• If HITKEEP_S3_ACCESS_KEY_ID and HITKEEP_S3_SECRET_ACCESS_KEY are both set, HitKeep uses static credentials.
• If neither is set, HitKeep uses the AWS credential chain (environment variables, shared config, instance profiles, STS, SSO).

Flag	Environment variable	Default	Description
--s3-access-key-id	HITKEEP_S3_ACCESS_KEY_ID	""	S3 access key ID (static credentials)Sensitive value; masked in safe configuration output.
--s3-endpoint	HITKEEP_S3_ENDPOINT	""	S3 custom endpoint (MinIO, R2, Spaces)
--s3-region	HITKEEP_S3_REGION	us-east-1	S3 region
--s3-secret-access-key	HITKEEP_S3_SECRET_ACCESS_KEY	""	S3 secret access key (static credentials)Sensitive value; redacted in safe configuration output.
--s3-session-token	HITKEEP_S3_SESSION_TOKEN	""	S3 session token (STS temporary credentials)Sensitive value; redacted in safe configuration output.
--s3-url-style	HITKEEP_S3_URL_STYLE	""	S3 URL style: path or vhost
--s3-use-ssl	HITKEEP_S3_USE_SSL	true	S3 use SSL (set false for local MinIO over HTTP)

See S3 Backups for end-to-end examples with AWS S3, MinIO, and Cloudflare R2.

Server & Networking

Settings for binding ports and clustering nodes.

Flag	Environment variable	Default	Description
--bind-addrDeprecated: -bind	HITKEEP_BIND_ADDR	0.0.0.0:7946	Address for cluster gossip
--join-addrDeprecated: -join	HITKEEP_JOIN_ADDR	""	Address of a peer to join
--node-nameDeprecated: -name	HITKEEP_NODE_NAME	hostname-timestamp	Unique node name

Optional MCP Route

MCP is disabled by default. When enabled, it is mounted on the leader’s main HTTP server and serves read-only aggregate analytics plus official documentation tools over MCP Streamable HTTP.

Flag	Environment variable	Default	Description
--mcp-docs-cache-minutes	HITKEEP_MCP_DOCS_CACHE_MINUTES	60	Minutes to cache fetched docs for MCP tools
--mcp-docs-enabled	HITKEEP_MCP_DOCS_ENABLED	true	Enable MCP tools and resources that read official HitKeep docs
--mcp-docs-url	HITKEEP_MCP_DOCS_URL	https://hitkeep.com	Base URL for official HitKeep docs used by MCP docs tools
--mcp-enabled	HITKEEP_MCP_ENABLED	false	Enable the optional leader-only MCP server
--mcp-max-range-days	HITKEEP_MCP_MAX_RANGE_DAYS	366	Maximum analytics date range in days for MCP tools
--mcp-path	HITKEEP_MCP_PATH	/mcp	MCP server HTTP path on the main HitKeep HTTP server

See Official MCP Server for setup and tool details.

Optional AI Model Configuration

AI-powered product features are disabled by default. When enabled, HitKeep uses the configured provider/model route and stores only audit metadata plus the validated customer-visible output. Ask AI has its own feature gate because it is an interactive dashboard-session feature.

Self-hosted operators configure the HitKeep route and budget fields through environment variables or flags. Provider credentials are resolved by the wrapped goAI provider, so set the selected provider’s own environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or AWS credentials. Use the goAI supported providers documentation for provider-specific auth and endpoint variables. HitKeep Cloud can run the same route fields as cloud-managed configuration, with provider secrets managed outside the customer dashboard.

Use this reference for exact field names and defaults. For model selection, setup examples, and budget sizing, see AI Model Configuration.

Route production AI through a gateway

HitKeep has a rudimentary global AI request and token limiter. It is a coarse process-level safeguard, not per-user, per-site, per-provider-key, or a security policy engine. For production use, route model traffic through an AI gateway or provider policy layer that can enforce detailed quotas, model allowlists, key isolation, audit logging, redaction, and network controls. See GoAI’s supported provider options and generic OpenAI-compatible provider docs for the underlying base URL, token, header, and custom endpoint patterns.

Flag	Environment variable	Default	Description
--ai-api-key	HITKEEP_AI_API_KEY	""	Optional explicit AI provider API key, bearer token, or gateway key; provider-native goAI env vars are preferredSensitive value; redacted in safe configuration output.
--ai-base-url	HITKEEP_AI_BASE_URL	""	Optional explicit AI provider or gateway base URL
--ai-budget-window	HITKEEP_AI_BUDGET_WINDOW	1440	AI local budget window in minutes
--ai-enabled	HITKEEP_AI_ENABLED	false	Enable optional AI-powered product features
--ai-model	HITKEEP_AI_MODEL	""	AI model identifier for the configured provider
--ai-provider	HITKEEP_AI_PROVIDER	""	AI provider key supported by HitKeep's GoAI router
--ai-region	HITKEEP_AI_REGION	""	Optional explicit AI provider region override
--ai-request-limit	HITKEEP_AI_REQUEST_LIMIT	100	Maximum AI requests per budget window; 0 disables local request cap
--ai-timeout-seconds	HITKEEP_AI_TIMEOUT_SECONDS	30	AI provider request timeout in seconds
--ai-token-limit	HITKEEP_AI_TOKEN_LIMIT	100000	Maximum AI tokens per budget window; 0 disables local token cap
--ask-ai-enabled	HITKEEP_ASK_AI_ENABLED	false	Enable the optional dashboard Ask AI assistant; requires HITKEEP_AI_ENABLED and a configured AI model

The token limit is a local usage budget, not the model context window. The current Opportunities enrichment path asks the provider for a small validated JSON object and caps provider output at 900 tokens. Provider model limits still apply upstream.

The admin AI status endpoint reports whether AI is enabled and configured, the provider/model label, the configuration mode (self_hosted or cloud_managed), the current request/token budget state, and a safe last-error category. It never returns provider secrets, raw prompts, raw provider responses, or raw external error bodies.

Opportunities use deterministic detectors for opportunity type, evidence, impact, confidence, and status. AI may summarize or explain only cited evidence. The saved API output uses translation keys plus interpolation params so dashboard copy can be localized without changing stored records.

For a direct provider route, configure the HitKeep route and the provider’s goAI credential environment:

HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=your-json-capable-model
OPENAI_API_KEY=provider_key_from_your_secret_store

For an OpenAI-compatible gateway, configure a HitKeep base URL. Set HITKEEP_AI_API_KEY only when the gateway expects a bearer token:

HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=hitkeep-ai
HITKEEP_AI_BASE_URL=https://ai-gateway.example.com/v1

See AI Model Configuration for setup examples, Opportunity Recommendations for saved recommendation behavior, and Ask AI for dashboard-session assistant behavior, permissions, and one-off chat boundaries.

Outbound Webhook Delivery

Outbound operational webhooks are enabled as part of the normal HitKeep runtime. Most installations can keep these defaults. Production destinations require HTTPS and must resolve only to public addresses; the development-target flag removes that protection for explicit local testing.

Flag	Environment variable	Default	Description
--webhook-allow-development-targets	HITKEEP_WEBHOOK_ALLOW_DEVELOPMENT_TARGETS	false	Allow HTTP and private webhook destinations for explicit development/self-host testing
--webhook-delivery-concurrency	HITKEEP_WEBHOOK_DELIVERY_CONCURRENCY	8	Maximum concurrent outbound webhook deliveries
--webhook-delivery-timeout	HITKEEP_WEBHOOK_DELIVERY_TIMEOUT	10	Outbound webhook request timeout in seconds
--webhook-max-attempts	HITKEEP_WEBHOOK_MAX_ATTEMPTS	6	Maximum outbound webhook delivery attempts
--webhook-per-endpoint-concurrency	HITKEEP_WEBHOOK_PER_ENDPOINT_CONCURRENCY	1	Maximum concurrent deliveries for one webhook
--webhook-retention-days	HITKEEP_WEBHOOK_RETENTION_DAYS	30	Days to retain webhook delivery logs
--webhook-retry-base-seconds	HITKEEP_WEBHOOK_RETRY_BASE_SECONDS	30	Initial outbound webhook retry delay in seconds
--webhook-retry-max-seconds	HITKEEP_WEBHOOK_RETRY_MAX_SECONDS	21600	Maximum outbound webhook retry delay in seconds
--webhook-sweep-seconds	HITKEEP_WEBHOOK_SWEEP_SECONDS	30	Seconds between pending webhook delivery recovery sweeps

See Signed Outbound Webhooks for event scopes, HMAC verification, retry semantics, destination validation, and secret rotation.

Google Search Console

Self-hosted installs must configure a Google OAuth web client before teams can connect Search Console, map properties, and import Search Analytics rows.

Flag	Environment variable	Default	Description
--google-search-console-client-id	HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID	""	Google Search Console OAuth client ID
--google-search-console-client-secret	HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET	""	Google Search Console OAuth client secretSensitive value; redacted in safe configuration output.
--google-search-console-redirect-url	HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL	""	Google Search Console OAuth callback URL override

Enable the Google Search Console API in the same Google Cloud project that owns the OAuth client. See Google Search Console Integration for the Google Cloud setup and sync behavior.

Social Sign-In

OAuth client pairs enable the corresponding social provider. Callback URLs derive from HITKEEP_PUBLIC_URL; Microsoft defaults to the common tenant selector. Keep client secrets in your deployment secret store.

Flag	Environment variable	Default	Description
--social-github-client-id	HITKEEP_SOCIAL_GITHUB_CLIENT_ID	""	GitHub social sign-in OAuth client ID
--social-github-client-secret	HITKEEP_SOCIAL_GITHUB_CLIENT_SECRET	""	GitHub social sign-in OAuth client secretSensitive value; redacted in safe configuration output.
--social-google-client-id	HITKEEP_SOCIAL_GOOGLE_CLIENT_ID	""	Google social sign-in OAuth client ID
--social-google-client-secret	HITKEEP_SOCIAL_GOOGLE_CLIENT_SECRET	""	Google social sign-in OAuth client secretSensitive value; redacted in safe configuration output.
--social-microsoft-client-id	HITKEEP_SOCIAL_MICROSOFT_CLIENT_ID	""	Microsoft social sign-in OAuth client ID
--social-microsoft-client-secret	HITKEEP_SOCIAL_MICROSOFT_CLIENT_SECRET	""	Microsoft social sign-in OAuth client secretSensitive value; redacted in safe configuration output.
--social-microsoft-tenant	HITKEEP_SOCIAL_MICROSOFT_TENANT	common	Microsoft tenant selector: common, organizations, consumers, or tenant UUID
--social-signup-enabled	HITKEEP_SOCIAL_SIGNUP_ENABLED	false	Enable managed-cloud account creation through configured social providers

See Configure Social Sign-In for exact Google, GitHub, and Microsoft callback URLs, provider-console steps, Docker Compose examples, account rules, and troubleshooting.

Email (SMTP)

Required for “Forgot Password” functionality.

Flag	Environment variable	Default	Description
--mail-driver	HITKEEP_MAIL_DRIVER	smtp	Mail driver
--mail-encryption	HITKEEP_MAIL_ENCRYPTION	tls	Mail encryption
--mail-from-address	HITKEEP_MAIL_FROM_ADDRESS	hitkeep@localhost	From Email
--mail-from-name	HITKEEP_MAIL_FROM_NAME	HitKeep	From Name
--mail-host	HITKEEP_MAIL_HOST	""	SMTP Host
--mail-insecure-skip-verify	HITKEEP_MAIL_INSECURE_SKIP_VERIFY	false	Disable Cert validation
--mail-password	HITKEEP_MAIL_PASSWORD	""	SMTP PasswordSensitive value; redacted in safe configuration output.
--mail-port	HITKEEP_MAIL_PORT	587	SMTP Port
--mail-username	HITKEEP_MAIL_USERNAME	""	SMTP Username

Rate Limiting

HitKeep includes a built-in rate limiter to protect against abuse. Limits are defined per IP address.

Ingestion (/ingest, /ingest/event, /api/ingest/server/*)

High-throughput endpoints for the browser tracker and trusted server-side pageview or event ingest. Server-side ingest still requires an API client token and can be called by non-browser clients without Origin or Referer headers, but it uses this ingest limiter because log forwarders and edge workers often send bursts from one IP.

Flag	Environment variable	Default	Description
--api-burst	HITKEEP_API_BURST	20	API burst
--api-rate-limitDeprecated: -api-rate	HITKEEP_API_RATE_LIMIT	10	API rate limit
--auth-burst	HITKEEP_AUTH_BURST	5	Auth burst
--auth-rate-limitDeprecated: -auth-rate	HITKEEP_AUTH_RATE_LIMIT	2	Auth rate limit
--ingest-burst	HITKEEP_INGEST_BURST	40	Ingest burst
--ingest-rate-limitDeprecated: -ingest-rate	HITKEEP_INGEST_RATE_LIMIT	20	Ingest rate limit
--webhook-burst	HITKEEP_WEBHOOK_BURST	60	Webhook burst
--webhook-rate-limitDeprecated: -webhook-rate	HITKEEP_WEBHOOK_RATE_LIMIT	30	Webhook rate limit

API (/api/*)

General data retrieval endpoints.

Imports (/api/sites/*/imports/*)

Import lifecycle and chunk upload requests use the normal API limiter above. The staged upload size is controlled by HITKEEP_IMPORT_MAX_STAGE_BYTES. Stale staged import files are cleaned after HITKEEP_IMPORT_STAGE_RETENTION_DAYS; set the value to 0 to disable cleanup.

Authentication (/api/login, etc)

Strict limits to prevent brute-force attacks.

Incoming Webhook Routes

Incoming cloud integration webhook routes use a separate limiter. These limits do not control outbound operational webhook delivery.

Trusted Proxies

Use this when HitKeep is behind a reverse proxy or load balancer and you want to trust forwarded headers. This affects rate limiting, spam checks, IP exclusions, and derived IP metadata accuracy for country, region, city, provider, and ASN fields. HitKeep uses the resolved IP transiently for these decisions and does not store the raw visitor IP.

Flag	Environment variable	Default	Description
--trusted-proxies	HITKEEP_TRUSTED_PROXIES	*	Trusted proxy CIDRs (comma-separated) or '*' to trust all

Behavior:

• The default * expands to all IPv4 and IPv6 networks.
• With *, HitKeep uses the first valid IP in X-Forwarded-For when that header is present.
• If set to CIDRs, HitKeep only trusts forwarded headers when the direct connection IP is in the trusted list.
• If set to an empty value, HitKeep ignores forwarded headers and uses the direct connection IP.

Internals (Advanced)

Configuration for embedded components. You generally do not need to change these unless you are developing HitKeep or have port conflicts on the host network.

Flag	Environment variable	Default	Description
--nsq-http-address	HITKEEP_NSQ_HTTP_ADDRESS	127.0.0.1:4151	Internal NSQ HTTP
--nsq-tcp-address	HITKEEP_NSQ_TCP_ADDRESS	127.0.0.1:4150	Internal NSQ TCP

Managed Cloud Runtime

Cloud-hosted builds have additional internal HITKEEP_CLOUD_* and HITKEEP_STRIPE_* variables used by managed HitKeep Cloud. They are not needed for self-hosted installs.