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.12 is the latest stable release, published August 22, 2026. The product facts on this page were last substantively reviewed on July 14, 2026. Resource figures are observations, not universal guarantees.

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

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

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

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

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

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

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

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

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

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

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

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

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