---
title: "HitKeep Flags and Environment Variables | HitKeep"
description: "Reference for HitKeep CLI flags and environment variables, including database paths, JWT secrets, rate limits, SMTP, S3 backups, MCP, AI, and trusted proxies."
canonical: "https://hitkeep.com/reference/configuration/"
---

# HitKeep Flags and Environment Variables

HitKeep follows the [12-factor app](https://12factor.net/) 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](https://hitkeep.com/reference/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 URLURL value; credentials, query parameters, and fragments are redacted in safe configuration output. |

### 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](https://hitkeep.com/guides/tracking/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](https://hitkeep.com/guides/installation/performance/) 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](https://hitkeep.com/guides/tracking/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 pathURL value; credentials, query parameters, and fragments are redacted in safe configuration output. |
| --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](https://hitkeep.com/guides/data/backups-and-restore/) and [S3 Backups](https://hitkeep.com/guides/data/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)URL value; credentials, query parameters, and fragments are redacted in safe configuration output. |
| --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](https://hitkeep.com/guides/data/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 toolsURL value; credentials, query parameters, and fragments are redacted in safe configuration output. |
| --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](https://hitkeep.com/guides/integrations/mcp/) 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](https://goai.sh/providers/) 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](https://hitkeep.com/guides/admin/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](https://goai.sh/providers/) and [generic OpenAI-compatible provider](https://goai.sh/providers/compat.html) 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 URLURL value; credentials, query parameters, and fragments are redacted in safe configuration output. |
| --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](https://hitkeep.com/guides/admin/ai-model-configuration/) for setup examples, [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/) for saved recommendation behavior, and [Ask AI](https://hitkeep.com/guides/analytics/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](https://hitkeep.com/guides/integrations/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 overrideURL value; credentials, query parameters, and fragments are redacted in safe configuration output. |

Enable the **Google Search Console API** in the same Google Cloud project that owns the OAuth client. See [Google Search Console Integration](https://hitkeep.com/guides/integrations/google-search-console/) 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](https://hitkeep.com/guides/security/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.

[Previous Introduction](https://hitkeep.com/guides/introduction/)[Next HitKeep Cloud pricing](https://hitkeep.com/pricing/)