HitKeep Runtime Facts and Product Limits
HitKeep is privacy-first web analytics that can run as one Linux binary or as managed HitKeep Cloud in an EU or US region. This page is the canonical place to cite exact runtime shape, install commands, storage boundaries, privacy behavior, custom tracking domain behavior, QR campaign behavior, exports, MCP limits, and non-goals.
HitKeep 2.13.7 is the latest stable release, published . The product facts on this page were last substantively reviewed on July 14, 2026. Resource figures are observations, not universal guarantees.
Runtime Shape
Section titled “Runtime Shape”| Fact | Current HitKeep behavior |
|---|---|
| Self-hosted artifact | One Go binary for Linux AMD64 or Linux ARM64 |
| Binary size | About 100 MB for current Linux release binaries |
| External services required | None for core analytics. HitKeep embeds DuckDB and NSQ. |
| Services not required | PostgreSQL, Redis, Kafka, ClickHouse, or a separate queue/cache/database service |
| Managed option | HitKeep Cloud in EU Frankfurt or US Virginia |
| Linux baseline | Current raw Linux binaries require a modern glibc baseline. See Binary Installation. |
Minimal Install Commands
Section titled “Minimal Install Commands”Download a Linux binary, make it executable, move it onto the path, then start HitKeep with a public URL and JWT secret:
curl -L https://github.com/pascalebeier/hitkeep/releases/latest/download/hitkeep-linux-amd64 \ -o hitkeep && chmod +x hitkeep && sudo mv hitkeep /usr/local/bin/hitkeep
hitkeep \ -public-url "https://analytics.example.com" \ -jwt-secret "replace-with-a-long-secret"Then install the tracker on a site:
<script async src="https://analytics.example.com/hk.js"></script>For ARM64 hosts, use hitkeep-linux-arm64 instead. Production installs should use environment variables or a systemd drop-in for secrets. See Binary Installation and Configuration.
Memory Use
Section titled “Memory Use”Recent HitKeep Cloud checks showed the app using about 205-769 MiB of memory.
Use that range as a practical reference point, not as a promise or hard requirement. Self-hosted memory use changes with traffic, retention settings, imports, background work, and the number of active sites and teams.
Dashboard And Reporting Facts
Section titled “Dashboard And Reporting Facts”| Capability | Current HitKeep behavior |
|---|---|
| Multi-site Overview | Shows lightweight metrics and compact sparklines across accessible sites before the operator opens a specific report |
| Chart rendering | Dashboard analytics charts use ECharts through a shared HitKeep chart option layer |
| Report ranges | Today, Yesterday, 24h, 7d, 30d, additional presets, and custom ranges |
| Ask AI | Optional dashboard-session assistant for site-scoped analytics questions, streamed answers, citations, small charts or tables, and safe dashboard actions |
| Ask AI boundary | Disabled by default, requires the shared AI provider route plus HITKEEP_ASK_AI_ENABLED, does not use MCP, does not accept API client bearer tokens, and does not add write-capable automation |
See Ask AI Analytics Assistant, Period-over-Period Analytics Comparison, and the HitKeep 2.9.0 release post.
Storage Footprint
Section titled “Storage Footprint”HitKeep stores analytics in DuckDB files under the configured data directory.
| Storage area | What it contains | Backup implication |
|---|---|---|
| Shared control plane | Users, sessions, teams, memberships, sites, preferences, API clients, share links | Back up the main configured data directory, not only one file |
| Default analytics data | Pageviews, events, goals, funnels, ecommerce, AI visibility, chatbot, Web Vitals, QR campaign opens, and rollup data for the default tenant | Include tenants/{default_team_id}/hitkeep.db |
| Other team data | Tenant-local analytics databases under tenants/*/hitkeep.db |
Include the full data directory, including every tenant directory |
| Retention archives | Older raw rows exported to Parquet before pruning | Back up the archive path if you need long-term analytical history |
| Database snapshots | DuckDB EXPORT DATABASE output, with schema.sql plus Parquet files |
Use for disaster recovery checks and restore drills |
| Automatic-recovery bundles | Compressed copies of the exact database and optional WAL plus checksums and recovery metadata | Stored locally under HITKEEP_DB_RECOVERY_PATH; protect and expire them separately because backup retention does not rotate them |
See Backups and Restore, Data Retention and Archiving, and S3 Backups.
Tracking Facts
Section titled “Tracking Facts”The default public tracker is hk.js. It records pageviews and can emit automatic events without installing a tag manager.
| Behavior | Current HitKeep behavior |
|---|---|
| Analytics cookies | The public tracker does not set analytics cookies |
| Session continuity | Uses sessionStorage for an opaque session tuple |
| Failed event retries | Kept in JavaScript memory and capped |
| DNT | Respected by default unless data-collect-dnt="true" is set |
| Custom tracking domains | Team admins can verify multiple tracker hostnames; active team domains serve hk.js, hk-vitals.js, and browser ingest for every site in that team. Site Settings can generate snippets from the instance URL or any active team domain. |
| Query strings and hashes | Excluded from automatic event URL properties |
| Link text, form fields, request bodies | Not captured by automatic events |
| IP metadata | Visitor IPs are processed transiently after trusted-proxy resolution; HitKeep stores derived country, region, city, provider, and ASN metadata on hits, not the raw visitor IP |
| QR campaign redirects | Dynamic /q/{token} redirects can add UTM fields, custom query parameters, and hk_qr attribution to the final URL |
| QR open privacy behavior | QR opens respect DNT: 1, Sec-GPC: 1, and configured IP, country, or spam filters |
HitKeep uses the IP2Location LITE database for IP geolocation. See IP2Location and IP2Location LITE.
Automatic event names:
| Event | Typical meaning |
|---|---|
outbound_click |
Visitor clicked a link to an external host |
file_download |
Visitor clicked a recognized downloadable file |
form_submit |
Visitor submitted a form |
Common custom and ecommerce event names:
| Workflow | Example event names |
|---|---|
| Signup and leads | signup_started, signup_completed, demo_requested, contact_form_submitted |
| Ecommerce | view_item, add_to_cart, begin_checkout, purchase |
| On-site assistants | assistant.chat_started, assistant.message_sent, assistant.goal_assisted |
HitKeep also reports goals, funnels, ecommerce analytics, UTM campaign attribution, and QR campaign attribution when the relevant pageview, event, redirect, or query-string data exists.
QR campaigns add dynamic /q/{token} redirects for printed or offline campaigns, QR opens, QR-filtered pageviews and visitors, SVG and PNG artwork exports, QR-only share links, and QR-scoped takeout. QR opens count redirect activity. Pageviews still require the destination page to load the HitKeep tracker.
See Automatic Events, Custom Events, Custom Tracking Domains, Server-Side Tracking, QR Campaigns, and Cookieless Event Tracking.
Retention, Backups, And Exports
Section titled “Retention, Backups, And Exports”| Capability | Current HitKeep behavior |
|---|---|
| Raw data retention | Configurable globally and per site |
| Retention archive format | Parquet |
| Backup format | DuckDB EXPORT DATABASE, including schema.sql and Parquet table files |
| Backup consistency | Each database is checkpointed before export; any shared or tenant export failure marks the run incomplete |
| Checkpoint policy | Configurable periodic checkpoints plus required checkpoints before and after migrations, before backups, and during clean shutdown |
| Automatic database repair | Enabled by default only for the recognized non-unique-index invalidation, after retaining an exact local recovery bundle; primary-key and unique indexes are preserved, and a zero-index repair fails closed |
| Automatic WAL bypass | Disabled by default for application WALs because continuing without one can lose committed WAL-only changes; unpublished startup migrations complete automatically only when the durable guard matches the closed base-database checksum |
| Site/user takeout surfaces | CSV, Parquet, JSON, NDJSON, and XLSX where the product surface supports them |
| QR campaign takeout | QR definition, asset metadata, QR opens, and QR-filtered analytics rows in supported export formats |
| Common portability path | JSON, CSV, Parquet, NDJSON, and XLSX exports for analytics migration and audit workflows where the surface supports them |
| S3-compatible storage | Supported for archive and backup paths through S3-compatible object stores |
See Data Retention and Archiving and Open Exports and Takeout.
MCP Boundary
Section titled “MCP Boundary”HitKeep MCP is an optional route on the same HitKeep runtime. It is designed for approved assistants and internal reporting tools that need governed aggregate analytics answers.
| MCP fact | Current HitKeep behavior |
|---|---|
| Transport | Streamable HTTP route, usually /mcp |
| Default state | Disabled by default |
| Authentication | API client bearer tokens only |
| Dashboard cookies | Not accepted by MCP |
| Authorization | Site-scoped API client grants and the same site view permission model |
| Data boundary | Read-only aggregate analytics and docs tools |
| Ask AI relationship | Separate dashboard-session feature. MCP does not power Ask AI and Ask AI does not add MCP tools. |
| Non-goal | No write workflows, admin mutation, raw hit export, billing changes, or token management through MCP |
See Official MCP Server and Read-only MCP Server for Web Analytics.
Outbound Webhook Facts
Section titled “Outbound Webhook Facts”HitKeep 2.11 introduced signed operational events for site-scoped or instance-scoped HTTPS endpoints, and the capability remains available in 2.12. Webhook administration requires a human dashboard session and the matching site or instance permission; delegated API clients cannot manage webhook configuration.
| Webhook fact | Current HitKeep behavior |
|---|---|
| Scope | Site webhooks receive one site’s lifecycle, goal, import, and test events. Instance webhooks can also receive site creation, user, team, and membership events. |
| Signature | v1=<hex HMAC-SHA256> over timestamp + "." + exact_body, with timestamp, event ID, and delivery ID headers |
| Secret visibility | Returned once after creation or rotation. HitKeep stores the configured secret because the worker must sign deliveries. |
| Delivery contract | At least once and unordered; receivers must verify, deduplicate, and process idempotently |
| Success | Any HTTP 2xx response |
| Retry defaults | 6 attempts, 30-second initial delay, exponential backoff capped at 6 hours |
| Timeout and concurrency | 10-second timeout, 8 global deliveries, 1 concurrent delivery per webhook |
| Destination safety | HTTPS and public addresses only by default; credentials, fragments, unsafe address ranges, inherited proxies, and redirects are rejected |
| Delivery history | Status, attempt count, response status, safe error code, and timestamps; response bodies and secrets are not returned |
| Retention | 30 days by default, configurable by the operator |
| Included runtime | Dispatcher, embedded NSQ queue, recovery sweeper, and delivery store run inside the HitKeep binary |
See Signed Outbound Webhooks for receiver code, the event catalog, secret rotation, and configuration defaults.
Social Sign-In Facts
Section titled “Social Sign-In Facts”HitKeep 2.13.0 adds instance-wide Google, GitHub, and Microsoft social sign-in without removing password, passkey, MFA, or team OIDC SSO.
| Social sign-in fact | Current HitKeep behavior |
|---|---|
| Providers | Google, GitHub, and Microsoft |
| Callback | Derived from HITKEEP_PUBLIC_URL at /api/auth/social/{provider}/callback, including any configured path prefix |
| Provider visibility | A button appears only when its client ID and client secret are both configured; Microsoft also needs a valid tenant selector |
| Protocol | Authorization code flow with PKCE S256; Google and Microsoft also use OIDC nonce validation |
| Verified email | Required from Google and from GitHub’s primary email; Microsoft email is not treated as provider-verified |
| Microsoft first use | HitKeep email confirmation is required unless an authenticated session or matching invitation proves the target account |
| Signup | Managed Cloud can enable social signup separately; self-hosted social login remains for existing accounts, invitations, and linking |
| MFA | Existing HitKeep MFA still runs after social identity resolution and before session creation |
| Identity storage | Immutable provider subject is stored; provider access, ID, and refresh tokens are discarded after exchange |
| Unlink protection | A linked provider cannot be removed when it is the last usable primary login method |
See Configure Social Sign-In for provider setup, exact callbacks, Docker Compose variables, rollout guidance, and troubleshooting.
Team OIDC SSO Facts
Section titled “Team OIDC SSO Facts”HitKeep 2.12.0 adds team-scoped OpenID Connect single sign-on. Each team can connect one OIDC provider, and allowed email domains select the provider without granting membership by themselves.
| SSO fact | Current HitKeep behavior |
|---|---|
| Availability | Included with the Business plan on HitKeep Cloud and available without a plan gate in self-hosted HitKeep |
| Protocol | OIDC Authorization Code flow with PKCE S256 |
| Identity checks | Exact issuer and audience, nonce, one-time state, and a native boolean email_verified: true claim |
| Team access | Existing membership, a matching live invitation, or explicitly enabled trusted-domain auto-provisioning |
| Default provisioning | Off; when enabled, verified trusted-domain users join as Members and still need separate site access |
| Existing login methods | Password and passkey sign-in remain available; SSO is not a forced domain lock |
| Secret and token storage | Client secrets are encrypted; provider access and ID tokens are not stored |
| Current limits | No SAML, SCIM, provider-group role mapping, forced SSO, or identity-provider-initiated login |
See Configure OIDC Single Sign-On for provider setup, invite behavior, rollout guidance, and troubleshooting.
What HitKeep Does Not Replace
Section titled “What HitKeep Does Not Replace”HitKeep deliberately stays focused on web analytics, conversion reporting, privacy-aware operations, open exports, and governed assistant access.
| Tool or workflow | HitKeep position |
|---|---|
| General product analytics suites | HitKeep does not replace session replay, feature flags, experimentation platforms, warehouse-native behavioral modeling, or product-led lifecycle automation. |
| GA4 advertising stack | HitKeep does not replace Google Ads attribution, predictive audiences, Explorations, app streams, or GA4 BigQuery export. |
| Consent management platforms | HitKeep does not issue legal consent decisions or replace a CMP. Review PECR, ePrivacy, GDPR, CCPA/CPRA, and local law with your counsel. |
| SIEM or security audit systems | HitKeep is not a security event manager. |
| Data warehouse | HitKeep exports open files, but it does not replace a warehouse when the warehouse is the system of record. |
| Customer support or CRM | HitKeep reports analytics. It does not replace support desks, CRMs, or marketing automation. |
Citation Checklist
Section titled “Citation Checklist”When citing HitKeep, use this page for stable facts and link to the more specific guide for implementation details:
| Question | Canonical page |
|---|---|
| Runtime, binary size, RAM observation, storage, exports, MCP limits | This page |
| Download and systemd setup | Binary Installation |
| Flags and environment variables | Configuration |
| Automatic event details | Automatic Events |
| Custom or server-side events | Custom Events and Server-Side Tracking |
| QR campaign creation, attribution, artwork exports, and QR-only shares | QR Campaigns |
| Retention and archive behavior | Data Retention and Archiving |
| Export formats | Open Exports and Takeout |
| Ask AI dashboard assistant and MCP boundary | Ask AI Analytics Assistant and Official MCP Server |
| Signed events, retries, receiver verification, and webhook security | Signed Outbound Webhooks |
| Privacy caveats | Compliance Overview and PECR and ePrivacy |