A Home Assistant Supervisor app for managing device certificates and remote access through Pangolin mTLS.
Status: Early access, October 30, 2026. Version 0.1.0-dev.18 adds collapsed iPhone/iPad, Mac, Windows and Android installation guides in the app. The device type controls the download: iPhone/iPad receive a ZIP containing the Companion identity and Safari profile; other devices receive the .p12 directly. See release readiness for the remaining production-release gates. Certificate creation is available after verified administrator setup and an HTTPS Home Assistant URL are configured. No prebuilt image or production release has been published.
The source, lockfile, app manifest and Dockerfile are in pangolin_access. Native amd64/aarch64 container builds and runtime checks passed on GitHub Actions. Selected HA ingress and initial iOS Companion checks passed as owner-reported results; broader compatibility remains unverified. See local development and prototype validation results.
This is a Home Assistant app (formerly called an add-on), so install it through the Home Assistant App Store, not HACS. HACS does not handle apps/add-ons. Use Home Assistant OS or a Supervised installation with the App Store.
- In Home Assistant, open Settings → Apps → Install app.
- Open the ⋮ menu in the upper right and select Repositories.
- Add
https://github.com/partytimeexcellent/ha-pangolin-mtls, then refresh the App Store if the repository does not appear immediately. - Open HA Pangolin Access from the new repository and select Install. This development version builds locally, so the first install may take a while.
- In the app’s Configuration, leave recovery administrator IDs empty for the initial setup. Set Home Assistant’s external URL to the HTTPS address you will use to open the app, or enter that address as the app’s Home Assistant URL override. Save and start the app.
- Select Open Web UI. In Home Assistant setup, review the URL, choose and save administrators, then select Check access. Create the CA in Device certificates, set expiry reminders there if desired, and take a protected Home Assistant backup.
- To install the public CA into Pangolin, enable its integration API and configure Traefik if self-hosted, then create an organization API key with the eight permissions. In Pangolin setup, enter the API address:
https://plus the hostname in yourint-api-routerHost(...)rule. The app adds/v1; for Cloud, enterhttps://api.pangolin.net. Enter the Organization ID and key, select Find public resources, then choose Install CA cert on the intended Home Assistant resource. Any error appears beside that resource. - Optionally select Enable mTLS after installing the CA for a disabled resource. Otherwise enable Client Certificate (mTLS) in Pangolin. Enroll a device, then test both rejection without a certificate and access with the enrolled device before enabling the resource.
Follow the full installation tutorial for Pangolin API routing, resource preparation and device enrollment. The app documentation provides a shorter checklist. Upgrading alone does not create a CA or device identity.
The intended deployment is one Supervisor-managed container containing the dashboard, API, PKI, enrollment, database, and diagnostics. An existing Pangolin server and a connected site that can reach Home Assistant are prerequisites. No additional certificate service or Compose deployment is required.
- Use TypeScript, Fastify, Zod, React/Vite, SQLite, and OpenSSL inside one container.
- Use an organization-scoped Pangolin integration API key and an explicitly supplied organization ID. Server-wide organization discovery requires root privileges and is excluded from the default workflow.
- Start with a dedicated shared CA. Pangolin's inspected mTLS implementation verifies CA trust but exposes no individual certificate revocation mechanism. Retiring a database record does not block a device. A lost device can require replacing the CA and re-enrolling every remaining device. The current prototype does not implement retirement or revocation controls.
- Enroll locally through authenticated Home Assistant ingress, then import the password-protected
.p12into Companion itself. No public provisioning service in the first release. - Prototype Apple clients and real Pangolin handshakes before implementing the full product. Source support is evidence, not a device compatibility certification.
Read ARCHITECTURE.md, SECURITY.md, research evidence, and ROADMAP.md. The experiment plan defines the evidence required to proceed.
- Removing Pangolin's final trusted CA disables mTLS. It must never be offered as a way to block all devices.
- A CA change does not prove that existing WebSockets or resumed TLS sessions have stopped working.
- Certificate import through iOS Settings/Safari does not automatically provision Companion.
- Home Assistant login remains required. mTLS adds another control at the edge.
- The app will not automatically edit Home Assistant configuration or unrelated Pangolin resources.
- Installation
- Short Pangolin connection-check routine
- iOS and iPadOS enrollment
- Device installation: iPhone/iPad, Mac, Windows and Android
- macOS enrollment
- Certificate management
- Troubleshooting
- Optional advanced checks
The iOS guide includes the scoped working import path; iPadOS and macOS acceptance and broader Apple features remain separate checks. Maintainer contact, license selection, and security reporting channel remain release decisions; this repository does not yet grant an open-source license. Separate encrypted CA recovery export and rotation remain release gates; use a protected Supervisor backup for the current prototype.