Skip to content
Start free in Cloud

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

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.

Use a bare origin when HitKeep owns a hostname:

Terminal window
HITKEEP_PUBLIC_URL=https://analytics.example.com

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

Terminal window
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 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 Env Variable Default Description
--custom-tracking-dns-target HITKEEP_CUSTOM_TRACKING_DNS_TARGET "" DNS hostname or IP address that custom tracking domains must resolve to. Empty defaults to the host from HITKEEP_PUBLIC_URL.
--custom-tracking-tls-mode HITKEEP_CUSTOM_TRACKING_TLS_MODE external TLS readiness mode for custom tracking domains. Use external when a reverse proxy or load balancer terminates TLS. Use caddy-on-demand with the optional Caddy ask flow.
--caddy-tls-ask-token HITKEEP_CADDY_TLS_ASK_TOKEN "" Secret path token required by /internal/caddy/on-demand-tls/{token}. Set this when using Caddy on-demand TLS. Redacted from config output.

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.

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)
--duckdb-memory-limit HITKEEP_DUCKDB_MEMORY_LIMIT (derived) Memory limit for each DuckDB database, e.g. 2GB. When unset, HitKeep derives a container-aware default: GOMEMLIMIT minus Go overhead when set, otherwise half of effective memory (cgroup limit or physical RAM) clamped between 1 GiB and 16 GiB. Set none to keep DuckDB’s own default of 80% of system RAM. Size explicit values to roughly twice your database file size so writes keep headroom. Each tenant database applies the same limit.
--duckdb-threads HITKEEP_DUCKDB_THREADS (GOMAXPROCS) Number of DuckDB worker threads per database. Defaults to GOMAXPROCS, which respects container CPU quotas. Lower values reduce peak query memory on small hosts.
--db-compact-on-start HITKEEP_DB_COMPACT_ON_START true Rewrite fragmented database files on startup (and tenant databases when they are first opened) to return space freed by retention and deletes to the operating system. DuckDB never shrinks files on its own, so long-running installs reclaim disk here. Compaction only runs when at least 25% of the file (and 64 MiB) is reclaimable, needs transient free disk roughly the size of the database, and is skipped safely when it cannot run.
--db-auto-recover HITKEEP_DB_AUTO_RECOVER true Automatically recover the exact allowlisted DuckDB index-invalidation failure after retaining a compressed database/WAL bundle. The repair removes only the five known unsafe Search Console control-table indexes.
--db-auto-recover-wal HITKEEP_DB_AUTO_RECOVER_WAL false After retaining an exact recovery bundle, automatically bypass the recognized unreplayable WAL. Enabling this accepts loss of committed changes that exist only in that WAL; leave it disabled when operator approval is required.
--db-checkpoint-interval HITKEEP_DB_CHECKPOINT_INTERVAL 5 Minutes between periodic DuckDB checkpoints. Required checkpoints still run after migrations, before backups, and during shutdown. Set to 0 to disable only the periodic checkpoint loop.
--db-recovery-path HITKEEP_DB_RECOVERY_PATH <data-path>/recovery Local directory for permission-restricted automatic-recovery bundles and resumable recovery markers. Treat this directory as production database material.
--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.

HitKeep’s resident memory is dominated by DuckDB’s buffer pool. HitKeep derives a bounded, container-aware limit automatically; explicit values follow one rule of thumb:

Terminal window
# Rule of thumb: about twice your hitkeep.db file size.
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.

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.

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.

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.

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)

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.

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.

Flag Env Variable Default Description
--ai-enabled HITKEEP_AI_ENABLED false Enable optional AI-powered product features.
--ask-ai-enabled HITKEEP_ASK_AI_ENABLED false Enable the optional dashboard Ask AI assistant. Requires --ai-enabled, a configured provider/model route, and a human dashboard session.
--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:

Terminal window
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:

Terminal window
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 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 Env Variable Default Description
--webhook-allow-development-targets HITKEEP_WEBHOOK_ALLOW_DEVELOPMENT_TARGETS false Allow HTTP and private webhook destinations for explicit development or self-host testing. Do not enable in production.
--webhook-delivery-timeout HITKEEP_WEBHOOK_DELIVERY_TIMEOUT 10 Outbound webhook request timeout in seconds.
--webhook-delivery-concurrency HITKEEP_WEBHOOK_DELIVERY_CONCURRENCY 8 Maximum concurrent outbound webhook deliveries.
--webhook-per-endpoint-concurrency HITKEEP_WEBHOOK_PER_ENDPOINT_CONCURRENCY 1 Maximum concurrent deliveries for one webhook.
--webhook-max-attempts HITKEEP_WEBHOOK_MAX_ATTEMPTS 6 Maximum delivery attempts before permanent failure.
--webhook-retry-base-seconds HITKEEP_WEBHOOK_RETRY_BASE_SECONDS 30 Initial retry delay in seconds.
--webhook-retry-max-seconds HITKEEP_WEBHOOK_RETRY_MAX_SECONDS 21600 Maximum retry delay in seconds.
--webhook-retention-days HITKEEP_WEBHOOK_RETENTION_DAYS 30 Days to retain delivery and attempt history. A value of 0 disables retention cleanup.
--webhook-sweep-seconds HITKEEP_WEBHOOK_SWEEP_SECONDS 30 Seconds between recovery sweeps for pending or interrupted deliveries.

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

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.

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

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

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

Section titled “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.

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.

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.

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.

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

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.

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 * Comma-separated list of trusted proxy CIDRs, or * to trust forwarded client IP 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.

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.

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.