Configuration Reference

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. See each table for details — deprecated flags are marked with an arrow.

General Settings

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

Flag	Env Variable	Default	Description
--public-url	HITKEEP_PUBLIC_URL	http://localhost:8080	Required. The public-facing URL where HitKeep is accessible. May include a path prefix such as https://www.example.net/hitkeep/. Used for dashboard asset URLs, browser ingest routing, CORS, email links, and JWT issuer validation.
--jwt-secret	HITKEEP_JWT_SECRET	(randomly generated)	Required for production. A long random string used to sign authentication tokens. If not provided, sessions will invalidate on restart.
--auth-remember-me-days	HITKEEP_AUTH_REMEMBER_ME_DAYS	30	Remember-me lifetime in days. The dashboard session API exposes this policy so the frontend can show remembered sign-in status accurately.
--auth-session-minutes	HITKEEP_AUTH_SESSION_MINUTES	15	Dashboard session lifetime in minutes. The frontend reads this policy and shows the remaining time.
--auth-session-warning-seconds	HITKEEP_AUTH_SESSION_WARNING_SECONDS	120	Seconds before session expiry when the dashboard warning appears. Values below 20 seconds are raised to 20.
--db-path	HITKEEP_DB_PATH	hitkeep.db	Path to the embedded DuckDB database file. In Docker, this is mapped to /var/lib/hitkeep/data/hitkeep.db. (Old flag: -db)
--data-path	HITKEEP_DATA_PATH	data	Base directory for tenant-local analytics databases and other local state. In multiteam installs, this whole tree is part of the backup boundary.
--http-addr	HITKEEP_HTTP_ADDR	:8080	The interface and port for the HTTP server to listen on. (Old flag: -http)
--log-level	HITKEEP_LOG_LEVEL	info	Logging verbosity. Options: debug, info, warn, error.
--healthcheck	N/A	false	Run the healthcheck client and exit instead of starting the server.

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.

Data Management

Flag	Env Variable	Default	Description
--archive-path	HITKEEP_ARCHIVE_PATH	archive	Directory for exports, rollups, and archival artifacts.
--data-retention-days	HITKEEP_DATA_RETENTION_DAYS	365	Default data retention window (days) for newly created sites. (Old flag: -retention-days)
--import-max-stage-bytes	HITKEEP_IMPORT_MAX_STAGE_BYTES	107374182400	Maximum staged import upload size in bytes. The default is 100 GiB.
--import-stage-retention-days	HITKEEP_IMPORT_STAGE_RETENTION_DAYS	7	Days to keep stale staged import upload files before automatic cleanup. Set to 0 to disable import staging cleanup.

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	Env Variable	Default	Description
--spam-filter-path	HITKEEP_SPAM_FILTER_PATH	""	Path to the cached spam-filter data. Empty uses <data-path>/spam-filter.json.
--spam-filter-auto-update	HITKEEP_SPAM_FILTER_AUTO_UPDATE	false	Automatically refresh OSS spam-filter feeds on the leader node.
--spam-filter-update-interval	HITKEEP_SPAM_FILTER_UPDATE_INTERVAL	1440	Minutes between 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	Env Variable	Default	Description
--backup-path	HITKEEP_BACKUP_PATH	"" (disabled)	Backup destination: local directory or s3:// URL. Empty disables backups.
--backup-interval	HITKEEP_BACKUP_INTERVAL	60	Minutes between backup runs.
--backup-retention	HITKEEP_BACKUP_RETENTION	24	Number of snapshots to keep before pruning older ones.

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	Env Variable	Default	Description
--s3-access-key-id	HITKEEP_S3_ACCESS_KEY_ID	""	AWS access key ID for static credential authentication.
--s3-secret-access-key	HITKEEP_S3_SECRET_ACCESS_KEY	""	AWS secret access key for static credential authentication.
--s3-session-token	HITKEEP_S3_SESSION_TOKEN	""	STS temporary session token (used with static credentials).
--s3-region	HITKEEP_S3_REGION	us-east-1	S3 region for the archive bucket.
--s3-endpoint	HITKEEP_S3_ENDPOINT	""	Custom S3-compatible endpoint (e.g., MinIO, Cloudflare R2, DigitalOcean Spaces).
--s3-url-style	HITKEEP_S3_URL_STYLE	""	URL addressing style: path or vhost. Empty uses the DuckDB default.
--s3-use-ssl	HITKEEP_S3_USE_SSL	true	Set to false for local S3-compatible endpoints over HTTP (e.g., MinIO dev).

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	Env Variable	Default	Description
--node-name	HITKEEP_NODE_NAME	hostname-timestamp	Unique identifier for this node in a cluster. (Old flag: -name)
--bind-addr	HITKEEP_BIND_ADDR	0.0.0.0:7946	The address used for cluster communication (Memberlist/Gossip). (Old flag: -bind)
--join-addr	HITKEEP_JOIN_ADDR	""	The address of an existing peer node to join when starting in clustered mode. (Old flag: -join)

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	Env Variable	Default	Description
--mcp-enabled	HITKEEP_MCP_ENABLED	false	Enable the optional leader-only MCP server.
--mcp-path	HITKEEP_MCP_PATH	/mcp	Streamable HTTP path mounted on the main HitKeep HTTP server. Empty values and / normalize to /mcp.
--mcp-max-range-days	HITKEEP_MCP_MAX_RANGE_DAYS	366	Maximum analytics and comparison date range accepted by MCP tools.
--mcp-docs-enabled	HITKEEP_MCP_DOCS_ENABLED	true	Enable MCP tools and resources that fetch official HitKeep docs.
--mcp-docs-url	HITKEEP_MCP_DOCS_URL	https://hitkeep.com	Official docs base URL used by MCP docs tools.
--mcp-docs-cache-minutes	HITKEEP_MCP_DOCS_CACHE_MINUTES	60	In-memory cache TTL for llms.txt and up to 128 markdown docs pages.

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.

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.

Flag	Env Variable	Default	Description
--ai-enabled	HITKEEP_AI_ENABLED	false	Enable optional AI-powered product features.
--ai-provider	HITKEEP_AI_PROVIDER	""	Provider key supported by the HitKeep goAI wrapper. Supported values include openai, openai-compatible, compat, gateway, bifrost, litellm, bedrock, anthropic, google, gemini, mistral, ollama, openrouter, deepseek, groq, xai, cerebras, cohere, perplexity, together, and fireworks.
--ai-model	HITKEEP_AI_MODEL	""	Model identifier for the configured provider.
--ai-base-url	HITKEEP_AI_BASE_URL	""	Optional explicit base URL passed to providers that support it. Required for OpenAI-compatible gateways such as LiteLLM or Bifrost. Direct providers can also use their goAI-native base URL variables, such as OPENAI_BASE_URL.
--ai-region	HITKEEP_AI_REGION	""	Optional explicit region passed to providers that support it. Providers such as Bedrock also read their native environment, such as AWS_REGION.
--ai-api-key	HITKEEP_AI_API_KEY	""	Optional static token passed to providers that support static API keys or bearer tokens. Prefer the selected goAI provider’s native environment variable. This value is redacted in logs and status responses.
--ai-timeout-seconds	HITKEEP_AI_TIMEOUT_SECONDS	30	Provider request timeout in seconds.
--ai-request-limit	HITKEEP_AI_REQUEST_LIMIT	100	Maximum AI requests per local budget window. Set to 0 to disable the local request cap.
--ai-token-limit	HITKEEP_AI_TOKEN_LIMIT	100000	Maximum AI tokens per local budget window. Set to 0 to disable the local token cap.
--ai-budget-window	HITKEEP_AI_BUDGET_WINDOW	1440	Local AI budget window in minutes.

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_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_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=opportunities-json
HITKEEP_AI_BASE_URL=https://ai-gateway.example.com/v1

See AI Model Configuration for setup examples and Opportunity Recommendations for the product behavior, permissions, API contract, and export boundary.

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	Env Variable	Default	Description
--google-search-console-client-id	HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_ID	""	Google OAuth web client ID used for Search Console connection and property access.
--google-search-console-client-secret	HITKEEP_GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET	""	Google OAuth web client secret. Keep this out of logs, screenshots, seed data, and support bundles.
--google-search-console-redirect-url	HITKEEP_GOOGLE_SEARCH_CONSOLE_REDIRECT_URL	""	Optional callback URL override. Empty derives /api/integrations/google-search-console/oauth/callback from HITKEEP_PUBLIC_URL.

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.

Email (SMTP)

Required for “Forgot Password” functionality.

Flag	Env Variable	Default	Description
--mail-driver	HITKEEP_MAIL_DRIVER	smtp	Currently only smtp is supported.
--mail-host	HITKEEP_MAIL_HOST	""	SMTP Server Hostname (e.g., smtp.postmarkapp.com).
--mail-port	HITKEEP_MAIL_PORT	587	SMTP Server Port.
--mail-username	HITKEEP_MAIL_USERNAME	""	SMTP Username.
--mail-password	HITKEEP_MAIL_PASSWORD	""	SMTP Password.
--mail-encryption	HITKEEP_MAIL_ENCRYPTION	tls	Encryption mode: tls (STARTTLS), ssl (Implicit TLS), or none.
--mail-from-address	HITKEEP_MAIL_FROM_ADDRESS	hitkeep@localhost	The email address messages are sent from.
--mail-from-name	HITKEEP_MAIL_FROM_NAME	HitKeep	The sender name displayed in inboxes.
--mail-insecure-skip-verify	HITKEEP_MAIL_INSECURE_SKIP_VERIFY	false	Set to true to accept self-signed certificates (not recommended for production).

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	Env Variable	Default	Description
--ingest-rate-limit	HITKEEP_INGEST_RATE_LIMIT	20.0	Requests per second allowed per IP. (Old flag: -ingest-rate)
--ingest-burst	HITKEEP_INGEST_BURST	40	Maximum burst size allowed per IP.

API (/api/*)

General data retrieval endpoints.

Flag	Env Variable	Default	Description
--api-rate-limit	HITKEEP_API_RATE_LIMIT	10.0	Requests per second allowed per IP. (Old flag: -api-rate)
--api-burst	HITKEEP_API_BURST	20	Maximum burst size allowed per IP.

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.

Flag	Env Variable	Default	Description
--auth-rate-limit	HITKEEP_AUTH_RATE_LIMIT	2.0	Requests per second allowed per IP. (Old flag: -auth-rate)
--auth-burst	HITKEEP_AUTH_BURST	5	Maximum burst size allowed per IP.

Webhooks

Public webhook endpoints use a separate limiter.

Flag	Env Variable	Default	Description
--webhook-rate-limit	HITKEEP_WEBHOOK_RATE_LIMIT	30.0	Requests per second allowed per IP for webhook endpoints. (Old flag: -webhook-rate)
--webhook-burst	HITKEEP_WEBHOOK_BURST	60	Maximum webhook burst size allowed per IP.

Trusted Proxies

Use this when HitKeep is behind a reverse proxy or load balancer and you want to trust forwarded headers. This affects both rate limiting and GeoIP resolution.

Flag	Environment Variable	Default	Description
--trusted-proxies	HITKEEP_TRUSTED_PROXIES	*	Comma-separated list of trusted proxy CIDRs, or * to trust forwarded headers from any direct peer.

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	Env Variable	Default	Description
--nsq-tcp-address	HITKEEP_NSQ_TCP_ADDRESS	127.0.0.1:4150	Bind address for the embedded NSQ TCP interface.
--nsq-http-address	HITKEEP_NSQ_HTTP_ADDRESS	127.0.0.1:4151	Bind address for the embedded NSQ HTTP API.

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.