Direct answer
Choose Custom during setup, enter the HTTPS base URL that serves your PostHog instance, and try OAuth discovery. If that deployment does not advertise OAuth with S256 PKCE, use a narrowly scoped personal API key fallback. The app calls the configured host directly; it does not proxy self-hosted analytics traffic.
Self-hosted PostHog changes the connection details, not the mobile workflow. The critical requirement is a stable HTTPS base URL that exposes OAuth metadata and the private API endpoints, or a personal API key with the required read access.
PostHog notes that self-hosters manage their own infrastructure, URLs, upgrades, and scaling risk. The mobile companion cannot diagnose the whole deployment, but a deliberate connection test can separate DNS, TLS, reverse-proxy, authentication, and project-scope problems.
Before you start
- A running self-hosted PostHog deployment reachable from the iPhone.
- A valid HTTPS hostname with a trusted certificate.
- OAuth support with S256 PKCE on that instance, or a personal API key created there with narrow read scopes.
- A project ID in the same instance, or permission for the connected credential to list projects.
Step-by-step instructions
Verify the host in Safari first
Open the base hostname on the iPhone and confirm DNS, TLS, and any VPN path work. If Safari cannot reach the host, the app cannot fix the network route.
Choose Custom in setup
Enter the origin that serves PostHog, including https:// and any required port. Use the base origin, not a dashboard URL with /project/... appended.
Try secure PostHog sign-in
Tap Continue with PostHog. HogScope reads the instance's standard OAuth metadata and requires S256 PKCE before opening its sign-in page. If OAuth is unavailable, expand the personal API key fallback and use a dedicated read-only key.
Test authenticated access
Run Test PostHog connection before choosing a project. This catches invalid credentials, TLS failures, and host-level API problems without mixing them with a project ID typo.
Discover or enter the project
Use a detected project when the credential can list them. Otherwise enter the numeric project ID manually, open the dashboard, and test the exact feature you need.
A clean diagnostic sequence
Network layer
Confirm the phone can resolve the host, complete TLS, and reach it through any required VPN or private network.
Authentication layer
Use Test connection to verify the bearer token against the selected host.
Authorization and data layer
Select the project, open Dashboard or Quick Query, and address a feature-specific forbidden response by reviewing only that read scope.
Options and limitations
- The app does not configure, upgrade, or secure a self-hosted PostHog deployment.
- Private CA certificates or TLS interception may not be trusted by iOS without device-level certificate configuration.
- A reverse proxy must forward the PostHog API paths and authorization headers used by the app.
- PostHog self-hosted feature/API behavior can differ as deployments move between commits or configurations.
Common mistakes
Entering a project page URL
Use the base origin, such as https://posthog.example.com, rather than a URL containing /project/123/dashboard.
Testing only on the server LAN
Verify the same iPhone network path you will use in practice, including VPN, split DNS, firewall, and certificate trust.
Blaming the key for a TLS error
Authentication starts after the secure connection succeeds. Fix DNS and certificate failures before changing scopes.
Troubleshooting
The host cannot be reached
Check Safari, DNS, VPN, firewall rules, port, and whether the reverse proxy listens on the public hostname.
The credential is unauthorized
Reconnect OAuth or create a fallback key in the same self-hosted instance, then confirm the app is not still pointed at US or EU Cloud.
Projects cannot be listed
The credential may authenticate without project-list access. Enter the project ID manually or grant the smallest project read scope needed for discovery.
Related questions
Does self-hosted PostHog data pass through the app developer's server?
No app-owned backend or proxy is implemented. Requests go from the device to the custom host you configure.
Can I use an HTTP-only local hostname?
The intended setup is HTTPS with a certificate trusted by iOS. An insecure or privately trusted host may be blocked or require device-level network and certificate configuration outside the app.
Primary references
Product behavior above is based on the app source. These official PostHog references cover the underlying PostHog capability: