posthog-foss: the self-hostable PostHog mirror, and why you should not pull request here

A mirror, and the first thing the README tells contributors

posthog-foss is described as a read-only mirror of PostHog with all proprietary code removed, and the repository is synced automatically from the main PostHog repository. The practical consequence is stated in the same breath: raise issues and pull requests there, not here. That single line changes what this repository is for. It is a place to read and build the open source edition of PostHog, not a place to contribute to it, and a pull request opened here would be pointed at a codebase that is overwritten by the next sync. For an engineer evaluating the product, that is still the right place to look, because it shows exactly what the open source edition contains and what has been stripped out. For a contributor, the main repository is the only sensible destination, and this mirror should be treated as a read-only artefact of it.

What the open source edition actually covers

The README organises PostHog as a product context layer that ingests and stores analytics, errors, replays and business data so people and agents can query and act on it. The product areas are listed explicitly. On the analytics side there is product analytics with autocapture or manual event instrumentation, web analytics with a GA-like dashboard covering conversion, web vitals and revenue, and group analytics for multi-seat accounts. Observability covers error tracking, logs and distributed tracing that follow a trace to the line of code that broke. The ship-and-iterate group holds feature flags, experiments with statistical measurement of goal metrics, and early access features. There is also a data group built around a managed warehouse with 120 or more sources, a SQL editor with BI and visualisation, and data pipelines that filter, transform and route events to 25 or more tools or any webhook. Surveys, support and workflows round out the user-facing products.

An MCP server aimed at agents, installed with one command

The README contains a section that reads like it was written for coding agents, and it is the most concrete installation instruction in the document. The remote MCP server is at https://mcp.posthog.com/mcp, and it routes to the correct data region, US or EU, based on which one the human logged into. Installing it into Claude Code, Cursor, Codex, VS Code, Zed or PostHog Desktop takes a single command:

npx @posthog/wizard mcp add

The same section points out that the documentation is pre-indexed for models at posthog.com/llms.txt, that the changelog is available as plain Markdown at posthog.com/changelog.md, and that setup guides for each MCP client live in the model context protocol documentation. The wider agent story in the README includes AI observability for LLM applications with traces, generations, latency and cost, MCP analytics to see how agents use your own MCP server, PostHog AI for asking questions of product data, and a self-driving mode that turns signals such as errors and failed queries into researched reports and pull requests delivered to an Inbox for review.

Self-hosting means a multi-service stack, and Helm support is gone

The README points at two ways to get started, one labelled recommended and one labelled advanced, with the advanced one being self-hosting the open source hobby deploy. The repository layout shows what that means. The Dockerfile header states that it is used for self-hosted production builds, that the stages cover a shared Node.js base with pnpm, a frontend build for static assets, a plugin transpiler build, a Django app build that fetches dependencies and runs collectstatic, and a stage that fetches the GeoIP database, and it also notes that PostHog Cloud uses the same image re-tagged for its own use, with no separate cloud Dockerfile. Node.js services are built separately through Dockerfile.node. One line deserves attention from anyone planning a Kubernetes install: the Dockerfile says PostHog has sunset support for self-hosted K8s deployments, with a link to the announcement, even though a helm directory is still present in the tree.

A pinned Python and a Node base image define the runtime

The dependency lists show why this is not a light deployment. The Python project metadata pins requires-python to an exact version, 3.14.7, with a comment explaining that the pin is deliberate so upgrades are controlled explicitly, and it prefers compatible release specifiers over an unbounded floor so that security and tooling signals still work. The dependency list is long and reveals the architecture: Django around 5.2 with the REST framework, celery with celery-redbeat for scheduling, clickhouse-connect, clickhouse-driver and clickhouse-pool for the event store, dagster with its AWS, Celery, Docker, Kubernetes, pipes, Postgres, Slack and webserver plugins, dlt and deltalake for data movement, plus anthropic, boto3, aiohttp and aiokafka. The container side starts from node:24.13.0-bookworm-slim pinned by digest, enables corepack and installs pnpm, then sets COREPACK_ENABLE_NETWORK=0 so a registry stall fails fast rather than hanging the build.

Schema, migrations and the HogQL grammar are built from the monorepo

The build scripts in the root package.json show how a developer produces a working tree. The schema and the OpenAPI definitions are generated with the project tool, through bin/hogli build:schema and bin/hogli build:openapi, with a separate Python flavour via a shell script. The frontend is built per product group with pnpm --filter=@posthog/frontend run build:products. The most involved script generates the HogQL lexer and parser: it concatenates HogQLLexer.cpp.g4 with the common grammar, runs antlr to emit a C++ parser into common/hogql_parser, then does the same for the parser grammar with a visitor and without a listener, and removes the temporary lexer file. Database migrations have both a Postgres and a ClickHouse variant, and both script entries are marked deprecated in favour of a hogli migrations:run command, which tells you the preferred tooling is being migrated right now.

MIT licensed, no releases, and a mirror that moves daily

The licence situation is straightforward on the surface. The root package.json declares MIT, the package author is PostHog Inc., and the repository carries a LICENSE file at the top level. The README also states that everything is free to use with a monthly free tier for each product, with no card required, and points to a cloud signup for the US and EU regions. What is not a simple matter is the release story: this repository has no GitHub releases at all, and the last push was on 2026-10-20, one day before this writing. Since the mirror is synced automatically from the main repository, tags and version numbers in this tree follow the upstream project rather than being cut here. Anyone pinning a deployment should therefore pin an image digest or a commit rather than a tag, and should read the CHANGELOG.md file in the tree for what changed in the open source edition specifically.

Editorial conclusion

posthog-foss fits a team that wants product analytics, session replay, error tracking, feature flags and experiments in one self-hostable stack under an MIT licence, and that is prepared to operate Django, Celery, ClickHouse and a Node frontend rather than a single container. It does not fit a contributor who intends to file a pull request, since this repository is a mirror and the README asks for issues and pull requests in the main PostHog repository. Before deploying it, read the Helm sunset notice in the Dockerfile, read the self-hosting section of the README rather than the cloud pages, and confirm the pinned Python and Node versions in pyproject.toml and the Dockerfile match what your base images provide.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PostHog/posthog-foss on GitHub
4. README