Home Assistant Add-on

This Home Assistant add-on allows you to easily run Newt or Pangolin-CLI directly in Home Assistant.

FeaturesCopy Anchor Link

• Easy installation via Home Assistant Add-on Store
• Automated setup and execution of the Newt/Pangolin-CLI container
• Supports amd64, armv7, armhf, and aarch64 architectures
• Automatic restart on crash

InstallationCopy Anchor Link

NewtCopy Anchor Link

1. Add the GitHub Repository as an Add-on SourceCopy Anchor Link

• Go to Settings → Add-ons → Add-on Store.
• Click the menu (three dots in the top right) and select Repositories.
• Add the following URL:

  Copy Text

  https://github.com/boomam/home-assistant-addons

  or

  Copy Text

  https://github.com/Ferdinand99/home-assistant-newt-addon

  or

  Copy Text

  https://git.opland.net/Ferdinand99/home-assistant-newt-addon/

1. Click Add and wait for the repository to load.

2. Install and Start the Add-onCopy Anchor Link

Pangolin-CLICopy Anchor Link

1. Find Pangolin-CLI in the list and click Install.
2. Go to the Configuration tab and enter your values for:
   • PANGOLIN_ENDPOINT (e.g., https://example.com)
   • SITE_ID
   • SITE_SECRET
3. Click Save and then Start.
4. Check the Logs tab to verify that everything is running correctly.

NewtCopy Anchor Link

1. Find Newt Add-on in the list and click Install.
2. Go to the Configuration tab and enter your values for:
   • PANGOLIN_ENDPOINT (e.g., https://example.com)
   • NEWT_ID
   • NEWT_SECRET
3. Click Save and then Start.
4. Check the Logs tab to verify that everything is running correctly.

ConfigurationCopy Anchor Link

After installation, you can configure the add-on via the Home Assistant UI:

Pangolin-CLICopy Anchor Link

PANGOLIN_ENDPOINT: "https://example.com"
SITE_ID: "your_site_id"
SITE_SECRET: "your_site_secret"

NewtCopy Anchor Link

PANGOLIN_ENDPOINT: "https://example.com"
NEWT_ID: "your_newt_id"
NEWT_SECRET: "your_newt_secret"

Docker Environment VariablesCopy Anchor Link

Pangolin-CLICopy Anchor Link

The following environment variables are passed to the Newt container:

• PANGOLIN_ENDPOINT
• SITE_ID
• SITE_SECRET

NewtCopy Anchor Link

The following environment variables are passed to the Newt container:

• PANGOLIN_ENDPOINT
• NEWT_ID
• NEWT_SECRET

Exposing Home Assistant through addonCopy Anchor Link

1. Connect addon to your Pangolin by completing environment variables and starting the addon
2. In Pangolin create new HTTP resource for your new Tunnel with subdomain
3. Within the created Resource add new Target Configuration

4. In Home Assistant's configuration.yaml add these two sections:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
homeassistant:
  allowlist_external_urls:
    - "https://<subdomain>.example.com" # <-- Replace with URL of created resource in Pangolin

4.5: If you want to use SSO Authentication in Pangolin you need to set up the configuration.yaml like this:

http:
cors_allowed_origins:
- https://google.com
- https://www.home-assistant.io
ip_ban_enabled: true
login_attempts_threshold: 2
use_x_forwarded_for: true
trusted_proxies:
- 127.0.0.1
- Local IP of your NEWT instance
- VPS IP

You also need to set up Resource rules in the pangolin dashboard. See rule overview here.

Many thanks to steuerlexi for finding this out!

https://github.com/fosrl/pangolin/issues/757#issuecomment-2903774897

5. Restart Home Assistant and your new Pangolin Proxy should be alive

TroubleshootingCopy Anchor Link

Add-on does not start?Copy Anchor Link

• Check the logs in Home Assistant (Settings → Add-ons → Newt → Logs).
• Ensure that PANGOLIN_ENDPOINT, NEWT_ID, and NEWT_SECRET are set correctly.

Changes in configuration do not take effect?Copy Anchor Link

• Restart the add-on after making changes.

• Try removing the container manually:

  Copy Text

  docker stop newt
  docker rm newt

• Then start the add-on again.

Docker not available?Copy Anchor Link

• Home Assistant OS manages Docker automatically, but check if the system has access to Docker by running:

  Copy Text

  docker info

If this fails, there may be a restriction in Home Assistant OS.

Useful LinksCopy Anchor Link

• HA addon repo
• Home Assistant
• Docker Docs