🏡 Home Assistant Newt Add-on

---

📌 About this Add-on

This Home Assistant add-on allows you to easily run Newt from Fossorial directly in Home Assistant. The add-on lets you configure PANGOLIN_ENDPOINT, NEWT_ID, and NEWT_SECRET via the Home Assistant interface.

🚀 Features

• ✅ Easy installation via Home Assistant Add-on Store
• ✅ Automated setup and execution of the Newt container
• ✅ Supports amd64, armv7, armhf, and aarch64 architectures
• ✅ Automatic restart on crash
• ✅ Beta branch with AppArmor enabled by default

---

🧪 Beta Branch

The Beta branch contains the newest fixes and hardening updates before they are promoted to stable.

What is different in Beta?

• AppArmor support is included and enabled by default.
• Security improvements are tested here first.
• You may see faster update cadence than the stable branch.

If your host does not support AppArmor, use the stable branch instead.

---

🤝 Contributing

Want to help improve this project? Check out CONTRIBUTING.md to get started. Issues can be postet on our community discord! Discord!

---

🛠️ Installation

1️⃣ Add the GitHub Repository as an Add-on Source

1. Go to Settings → Add-ons → Add-on Store.
2. Click the menu (three dots in the top right) and select Repositories.
3. Add the following URL for the stable branch:

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

   or

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

4. For the beta branch, append #beta:

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

or

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

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

2️⃣ Install and Start the Add-on

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
   • custom_env_vars (optional) - Array of custom environment variables for NEWT
3. Click Save and then Start.
4. Check the Logs tab to verify that everything is running correctly.

---

Docker Environment Variables

Required Environment Variables

The following environment variables are required and must be configured:

• PANGOLIN_ENDPOINT - The endpoint where Pangolin resides
• NEWT_ID - Your Newt ID generated by Pangolin
• NEWT_SECRET - Your Newt secret for authentication

Custom Environment Variables

You can set additional environment variables through the add-on configuration using the custom_env_vars option. This allows you to configure any of the optional newt settings.

Example Configuration:

custom_env_vars:
  - "ACCEPT_CLIENTS=true"
  - "LOG_LEVEL=DEBUG"
  - "MTU=1420"

For a complete list of available environment variables and detailed descriptions, see the newt documentation.

How to Configure in Home Assistant UI

1. Go to Settings → Add-ons → Newt Add-on → Configuration
2. In the custom_env_vars field, add each environment variable on a separate line
3. Each entry should be in the format: VARIABLE_NAME=value
4. Click Save and restart the add-on

---

🛡️ Reverse Proxy / trusted_proxies Setup (Optional)

📘 Step-by-Step Instructions

1. Open your configuration.yaml file (usually located in /config).
2. Add or update the http: section to include use_x_forwarded_for and trusted_proxies:

NOTE: You should get a message in your Home-Assistant logs with the IP you need to set below when it's not already set

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.33.0/24  # Default range for Home Assistant add-ons
    - 127.0.0.1       # Localhost (if relevant)
    - 192.168.1.100   # Example: IP of your reverse proxy or VM host
    - 192.168.1.2     # Home-Assistant IP

🔎 How to Find Your Add-on or Proxy IP

If you're unsure of the IP range your add-on or reverse proxy uses, you can inspect the Docker network:

docker network inspect hassio

Look under the "Containers" section to find the IP of your Newt add-on or proxy. ✅ When to Use This

You need this setup if:

You're using a reverse proxy (e.g., NGINX, Traefik).

Your add-on or proxy accesses Home Assistant via internal IP (e.g., 172.30.x.x).

You're seeing token errors or "403: Forbidden" in the logs.

🔄 Final Step

After editing configuration.yaml, restart Home Assistant for the changes to take effect:

Go to Settings → System → Restart
or

Run via CLI:

ha core restart

---

🔍 Troubleshooting

💡 Add-on does not start?

• 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?

• Restart the add-on after making changes.

💡 Docker not available?

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

  docker info
  

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

---

🔗 Useful Links

• 📖 Newt Documentation
• 🏡 Home Assistant
• 🐳 Docker Docs

---

Made with ❤️ for Home Assistant users 🚀