Self-hosted push notification service for Home Assistant, based on ntfy v2.17.0.

---

#Pages

Page	Description
Installation	How to add the repository and install the add-on
Configuration	All configuration options explained
First-Start	Setting up your admin account and first notification
Admin-Panel	Using the web-based user management interface
Home-Assistant-Integration	rest_command, automation examples, official integration
Reverse-Proxy	Nginx / Traefik / Caddy configuration
iOS-Push-Notifications	Native iOS push via ntfy.sh upstream
Troubleshooting	Common issues and fixes
Known-Limitations	What the add-on cannot do and why
Backup-and-Restore	What gets backed up and how to restore
ntfy-Topics	Default topics and how to edit

---

#Quick Start

# Minimum config to get started
admin_username: admin
admin_password: your-secure-password

Then open ntfy at: http://homeassistant.local:4280

⚠️ Do not use the HA sidebar link — it shows a white screen due to an Ingress incompatibility. Always use the direct URL above.

---

#Ports

Port	Service
4280	ntfy server (web UI + API)
4281	Admin Panel (optional, enable via admin_panel: true)

#Step 1 — Add the Repository

1. Open Home Assistant
2. Go to Settings → Add-ons → Add-on Store
3. Click ⋮ (top right) → Repositories
4. Add:

   https://codeberg.org/wuest3nfuchs/ntfy-ha-app
   

5. Click Add → Close

#Step 2 — Install the Add-on

1. Search for ntfy in the add-on store
2. Click the add-on → Install
3. Wait for the installation to complete

#Step 3 — Configure

Go to the Configuration tab and set at minimum:

admin_username: admin
admin_password: your-secure-password

See Configuration for all available options.

#Step 4 — Start

Click Start. Check the Log tab and confirm you see:

Starting ntfy add-on …
Admin user 'admin' ready
Starting ntfy → http://homeassistant.local:4280

#Step 5 — Open the Web UI

⚠️ Do NOT use the HA sidebar link — it will show a white screen (known Ingress incompatibility). Always use the direct URL:

http://homeassistant.local:4280

Log in with the admin_username and admin_password you configured.

---

#Updating

When a new version of the add-on is available, HA will show an update notification in the add-on page. Click Update to install it.

The Forgejo Actions workflow automatically tracks new ntfy releases and opens a pull request when a new version is available.

All options are set in the add-on Configuration tab in Home Assistant.

---

#Required

Option	Type	Description
admin_username	string	Username for the bootstrap admin account. Created automatically on startup.
admin_password	string	Password for the admin account.

---

#General

Option	Default	Description
log_level	INFO	Log verbosity: TRACE, DEBUG, INFO, WARN, ERROR. Use DEBUG only for troubleshooting — it is very chatty.
base_url	—	External URL, e.g. https://ntfy.your-domain.com. Required for attachments and iOS push.
behind_proxy	false	Set to true if running behind Nginx, Traefik, or Caddy. Enables X-Forwarded-For support.

---

#Authentication & Access

Option	Default	Description
auth_default_access	deny-all	Default access for unauthenticated requests. Options: deny-all, read-only, write-only, read-write.
enable_signup	true	Allow users to self-register via the web UI.
enable_login	true	Show the login form in the web UI.
enable_reservations	false	Allow users to reserve topic names.

---

#Cache & Performance

Option	Default	Description
cache_duration	12h	How long messages are cached. Format: 12h, 7d, 0 (disabled).
keepalive_interval	45s	Keepalive interval for SSE/WebSocket connections. Increase to reduce hijacked connection log noise.
manager_interval	3m	How often the manager prunes old messages and prints stats.

---

#Attachments

Attachments require base_url to be set.

Option	Default	Description
attachment_file_size_limit	15M	Maximum size per attachment.
attachment_total_size_limit	5G	Total disk space used for all attachments.

---

#iOS Push Notifications

Option	Default	Description
upstream_base_url	—	Set to https://ntfy.sh to enable native iOS push. Also requires base_url.

See iOS-Push-Notifications for details.

---

#Admin Panel

Option	Default	Description
admin_panel	false	Enable the web-based admin panel on port 4281.

---

#Example: Full Configuration

log_level: INFO
base_url: "https://ntfy.your-domain.com"
behind_proxy: true
auth_default_access: deny-all
enable_signup: false
enable_login: true
enable_reservations: false
cache_duration: "12h"
attachment_file_size_limit: "15M"
attachment_total_size_limit: "5G"
keepalive_interval: "45s"
upstream_base_url: "https://ntfy.sh"
admin_panel: true
admin_username: admin
admin_password: "super-secret-password"

---

#Creating a Second Admin

The add-on supports one admin_username at a time in config. To bootstrap a second admin:

1. Change admin_username to the new username and admin_password to their password
2. Restart the add-on — the new account is created
3. Set admin_username back to your primary admin and restart again

Both accounts now exist in the database with the admin role.

#1. Set Your Admin Account

In the add-on Configuration tab:

admin_username: admin
admin_password: your-secure-password

Click Save, then Start.

#2. Check the Logs

Go to the Log tab. You should see:

Starting ntfy add-on …
Admin user 'admin' ready
Starting ntfy → http://homeassistant.local:4280

If you see errors, check the Troubleshooting page.

#3. Open the Web UI

⚠️ Use the direct URL — not the HA sidebar link.

http://homeassistant.local:4280

Click Log in and enter your admin credentials.

#4. Subscribe to a Topic

1. In the ntfy web UI, click + Add subscription (or the + button)
2. Enter a topic name, e.g. homeassistant
3. Click Subscribe

You are now subscribed. Any message published to this topic will appear here.

#5. Send Your First Notification

From the command line or any HTTP client:

curl -H "Authorization: Basic $(echo -n 'admin:your-secure-password' | base64)" \
     -d "Hello from ntfy!" \
     http://homeassistant.local:4280/homeassistant

Or use a token (recommended — see Home-Assistant-Integration):

curl -H "Authorization: Bearer tk_YOUR_TOKEN" \
     -H "Title: Test" \
     -d "Hello from ntfy!" \
     http://homeassistant.local:4280/homeassistant

The message should appear in the web UI and on any subscribed device.

#6. Install the ntfy App (Optional)

• Android: Google Play / F-Droid
• iOS: App Store

In the app, add your server: http://homeassistant.local:4280 and subscribe to your topics.

#7. Enable the Admin Panel (Optional)

Set admin_panel: true in the configuration and restart. The admin panel will be available at:

http://homeassistant.local:4281

See Admin-Panel for details.

#Option A — Official ntfy Integration (Recommended)

The official ntfy integration is available in Home Assistant 2023.x and later.

1. Go to Settings → Devices & Services → Add Integration
2. Search for ntfy
3. Enter:
   • Server URL: http://homeassistant.local:4280
   • Username: your username
   • Token: your access token (get one from ntfy Web UI → Account → Access Tokens)
4. Click Submit

Use either password or token — not both at the same time. Using both causes a credentials conflict error.

Once configured, use the notify service in automations:

action:
  - action: notify.ntfy_homeassistant
    data:
      message: "Front door opened"
      title: "Door Alert"

---

#Option B — rest_command (Manual)

#Step 1: Create an Access Token

1. Open http://homeassistant.local:4280
2. Log in → Account → Access Tokens → Create token
3. Label it Home Assistant and copy the token

Or use the Admin Panel → Tokens tab.

#Step 2: Add to configuration.yaml

rest_command:
  ntfy_send:
    url: "http://localhost:4280/{{ topic }}"
    method: POST
    headers:
      Authorization: "Bearer tk_YOUR_TOKEN_HERE"
      Title: "{{ title | default('') }}"
      Priority: "{{ priority | default('3') }}"
      Tags: "{{ tags | default('') }}"
    payload: "{{ message }}"
    content_type: "text/plain"

#Step 3: Use in Automations

action:
  - action: rest_command.ntfy_send
    data:
      topic: homeassistant
      message: "Motion detected in living room"
      title: "Motion Alert"
      priority: "4"
      tags: "warning,motion"

---

#Notification Priority

Value	Level	Description
1	min	Very low, no sound
2	low	Low, no vibration
3	default	Normal (default)
4	high	High priority, buzzes
5	urgent	Urgent, breaks Do Not Disturb

---

#Tags (Emoji Shortcodes)

Tags are displayed as emoji in the ntfy app. Examples:

Tag	Emoji	Use case
warning	⚠️	Alerts
door	🚪	Door sensors
motion	🏃	Motion sensors
fire	🔥	Fire alarm
battery	🔋	Low battery
house	🏠	General home

See the full list at docs.ntfy.sh/emojis.

---

#Advanced: Click URL

Open a specific HA dashboard when the notification is tapped:

headers:
  Authorization: "Bearer tk_YOUR_TOKEN"
  Title: "Motion Alert"
  Click: "http://homeassistant.local:8123/lovelace/security"

---

#Advanced: Sending Images as Attachments

Requires base_url to be configured in the add-on.

curl -H "Authorization: Bearer tk_YOUR_TOKEN" \
     -H "Title: Camera snapshot" \
     -T /config/www/snapshot.jpg \
     https://ntfy.your-domain.com/cameras

The Admin Panel is a separate web interface for managing users and tokens without using the ntfy command line. It runs on port 4281.

#Enable

In the add-on configuration:

admin_panel: true

Restart the add-on. The panel is then available at:

http://homeassistant.local:4281

#Login

Enter:

• Server URL: http://homeassistant.local:4280
• Username: your admin username
• Password: your admin password

You must have the admin role to log in.

---

#Dashboard

Shows a quick overview:

Field	Description
Status	OK ✓ if ntfy is healthy
Version	ntfy server version
Users	Number of regular users in the database
Messages	Total messages published

Click ↺ Refresh to update the stats.

---

#Users Tab

#View Users

All users in the ntfy database are listed with their role. The built-in * (anonymous) user is automatically hidden.

#Create a User

1. Enter a Username and Password
2. Click ＋ Create User

New users are always created with the user role. To create admin accounts, use admin_username in the add-on configuration.

#Change Password

Click Change PW next to a user, or scroll down to the Change Password card, enter the username and new password.

Admin accounts cannot have their password changed via the panel — manage them via the add-on configuration.

#Delete a User

Click 🗑 Delete next to a regular user and confirm.

Admin accounts cannot be deleted via the panel. The ntfy API returns 401 for admin account operations. Use the add-on configuration to manage admin accounts.

#Why Admin Accounts Show "manage via config"

The ntfy REST API restricts modification of admin accounts as a security measure. Admin accounts can only be managed via:

• admin_username / admin_password in the add-on config
• Restarting the add-on to apply changes

---

#Tokens Tab

#Create a Token

1. Enter a Label (e.g. Home Assistant)
2. Optionally set an Expiry date
3. Click ⬡ Create Token

The token is automatically copied to your clipboard. Use it in Home Assistant automations with Authorization: Bearer tk_YOUR_TOKEN.

#View / Delete Tokens

Token listing is not available in the admin panel due to browser cross-origin restrictions between port 4281 and port 4280. To view or delete existing tokens:

1. Open the ntfy web UI at http://homeassistant.local:4280
2. Log in with the user whose tokens you want to manage
3. Go to Account → Access Tokens

---

#Send Tab

Use this to send a test notification:

Field	Description
Topic	The topic name to publish to (e.g. test)
Title	Optional notification title
Priority	1 (min) to 5 (urgent), default 3 (default)
Tags	Comma-separated emoji tags (e.g. warning,door)
Click URL	URL to open when notification is tapped
Message	The notification body (required)

Click ▷ Send to publish. Check the ntfy web UI or your phone to confirm receipt.

---

#Info Tab

Shows server connection details and an auto-generated rest_command example for your configuration.yaml, pre-filled with your server URL.

By default, the ntfy iOS app polls your server for new messages (background fetch). For instant push notifications without polling, you need to route through ntfy.sh's Firebase/APNs infrastructure.

#Requirements

• A publicly accessible server URL (base_url)
• A ntfy.sh account (free tier is sufficient)

#Configuration

base_url: "https://ntfy.your-domain.com"
upstream_base_url: "https://ntfy.sh"

Restart the add-on after saving.

#How It Works

When a message is published to your self-hosted ntfy server, it sends a lightweight "poll request" to ntfy.sh. ntfy.sh then triggers an APNs push to the iOS device, which wakes the ntfy app. The app then fetches the actual message content from your server — ntfy.sh never sees the message body.

This means:

• ✅ Instant push without polling
• ✅ Message content stays on your server
• ✅ Free (uses ntfy.sh only as a signal relay)

#iOS App Setup

1. Install the ntfy iOS app
2. Open the app → Settings → Default server → enter your server URL
3. Subscribe to your topics
4. Notifications will now arrive instantly

#Troubleshooting

Notifications not arriving instantly:

• Confirm base_url is publicly accessible (test from outside your network)
• Confirm upstream_base_url: "https://ntfy.sh" is set and the add-on has been restarted
• Check the add-on log for upstream-base-url confirmation

Notifications delayed:

• The iOS app may fall back to polling if push is not configured correctly
• Check if the ntfy.sh servers are reachable from your server

• SE Default-Topics — "ha-alerts,ha-info,ha-notify,ha-system,ha-planty" (you can edit them yourself) example below

<label style="white-space:nowrap;">Monitor topics:</label>
<input type="text" id="sseTopicInput"value="ha-alerts,ha-info,ha-notify,ha-system,ha-planty"style="flex:1;min-width:200px;"/>

To access ntfy from outside your local network you need a reverse proxy with SSL/TLS. Set base_url and behind_proxy: true in the add-on configuration when using any of these setups.

---

#Nginx

server {
    listen 443 ssl;
    server_name ntfy.your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/ntfy.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ntfy.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:4280;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Required add-on config:

base_url: "https://ntfy.your-domain.com"
behind_proxy: true

---

#Traefik (Docker Labels)

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.ntfy.rule=Host(`ntfy.your-domain.com`)"
  - "traefik.http.routers.ntfy.tls=true"
  - "traefik.http.routers.ntfy.tls.certresolver=letsencrypt"
  - "traefik.http.services.ntfy.loadbalancer.server.port=4280"

Required add-on config:

base_url: "https://ntfy.your-domain.com"
behind_proxy: true

---

#Caddy

ntfy.your-domain.com {
    reverse_proxy localhost:4280
}

Caddy handles SSL automatically. Required add-on config:

base_url: "https://ntfy.your-domain.com"
behind_proxy: true

---

#Nginx Proxy Manager (HA Add-on)

1. Open Nginx Proxy Manager → Proxy Hosts → Add Proxy Host
2. Domain Names: ntfy.your-domain.com
3. Forward Hostname/IP: homeassistant.local (or the HA IP)
4. Forward Port: 4280
5. Enable Websockets Support
6. SSL tab → Request Let's Encrypt certificate

In the Advanced tab, add:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off;
proxy_read_timeout 3600s;

Required add-on config:

base_url: "https://ntfy.your-domain.com"
behind_proxy: true

---

#Notes

• Always set behind_proxy: true when using any reverse proxy, otherwise all clients appear as the same IP for rate limiting
• WebSocket support is required for real-time notifications
• proxy_read_timeout 3600s (or equivalent) prevents the proxy from closing long-lived SSE/WebSocket connections

#What Gets Backed Up

All ntfy data is stored in /data/ntfy/ inside the add-on container. This directory is automatically included in Home Assistant backups.

Path	Contents
/data/ntfy/user.db	User accounts, passwords (hashed), access tokens, ACL rules
/data/ntfy/cache/cache.db	Message cache (SQLite WAL mode)
/data/ntfy/attachments/	File attachments (only if base_url is configured)

#Creating a Backup

1. Go to Settings → System → Backups
2. Click Create backup
3. Choose Full backup or select the ntfy add-on in a Partial backup

The backup includes all three data directories above.

#Restoring

1. Go to Settings → System → Backups
2. Select the backup you want to restore from
3. Restore either the full backup or just the ntfy add-on

After restore:

• All users, passwords, and tokens are restored
• Message history (up to cache_duration) is restored
• Attachments are restored (if base_url was configured)

#Migrating to a New Installation

1. Create a backup on the old system
2. Copy the backup file to the new HA instance
3. Restore from that backup
4. Install and configure the ntfy add-on with the same admin_username/admin_password
5. Start the add-on — all data is available

#Manual Backup (Advanced)

If you want to back up just the ntfy data manually:

# From HA SSH add-on
cp -r /data/addon_configs/*/ntfy/ /backup/ntfy-manual-backup/
# or via the addon data path

The exact path depends on your HA installation. Check the add-on log for the data directory path.

#Notes

• The user.db contains bcrypt-hashed passwords — they cannot be recovered, but they restore correctly to a new installation
• Access tokens are stored in user.db and are fully restored
• The SQLite database uses WAL mode for better stability and crash recovery

All ntfy CLI commands require shell access inside the add-on container.

---

#Container Access

Use the HA SSH add-on to enter the container:

# Enter the ntfy container
docker exec -it $(docker ps | grep ntfy | awk '{print $1}') sh

# Set the auth database path (required inside container)
export NTFY_AUTH_FILE=/data/ntfy/user.db

# Now run any ntfy CLI command
ntfy user list

Or run a single command without entering the container:

docker exec -it $(docker ps | grep ntfy | awk '{print $1}') \
  sh -c 'NTFY_AUTH_FILE=/data/ntfy/user.db ntfy user list'

⚠️ NTFY_AUTH_FILE=/data/ntfy/user.db must always be set. Without it, ntfy cannot find the user database and will throw an error.

---

#User Management

Command	Description
ntfy user list	List all users and their roles
ntfy user add <username>	Create a new user (prompted for password)
ntfy user add --role=admin <username>	Create a new admin user
ntfy user del <username>	Delete a user
ntfy user change-pass <username>	Change a user's password
ntfy user change-role <username> admin	Promote user to admin role
ntfy user change-role <username> user	Demote admin to regular user

---

#Token Management

Command	Description
ntfy token list <username>	List all tokens for a user
ntfy token add <username>	Create a new access token
ntfy token add --label="HA" <username>	Create token with a label
ntfy token add --expires=30d <username>	Create token expiring in 30 days
ntfy token del <username> <token>	Delete a specific token

💡 Tokens created here are used in rest_command Authorization headers: Bearer tk_YOURTOKEN

---

#Access Control (ACL)

Command	Description
ntfy access	Show all ACL rules
ntfy access <username> <topic> read-write	Grant read + write on a topic
ntfy access <username> <topic> read-only	Grant read-only access
ntfy access <username> <topic> write-only	Grant write-only access
ntfy access <username> <topic> deny	Deny all access to a topic
ntfy access --reset	Remove all ACL rules

---

#Publish (CLI)

Command	Description
ntfy publish <topic> <message>	Send a message to a topic
ntfy publish --title="Alert" <topic> <message>	Send with title
ntfy publish --priority=5 <topic> <message>	Send with priority (1–5)
ntfy publish --title="Alert" --priority=5 <topic> <message>	Send with title + priority

---

#Practical Examples

#Create HA integration token

export NTFY_AUTH_FILE=/data/ntfy/user.db
ntfy token add --label="Home Assistant" haos
# → Copy the printed token into secrets.yaml

#Create a second admin

export NTFY_AUTH_FILE=/data/ntfy/user.db
ntfy user add --role=admin secondadmin
# → Enter password when prompted

#Restrict a topic to one user

export NTFY_AUTH_FILE=/data/ntfy/user.db
ntfy access haos HAOS read-write
ntfy access '*' HAOS deny
# → Only 'haos' user can read/write the HAOS topic

✅ Changes via CLI take effect immediately — no add-on restart required.

#Add-on won't start

Check the Log tab first. Common causes:

Symptom	Cause	Fix
Error parsing server.yml	Invalid config key in generated config	Check run.sh or report a bug
address already in use :4280	Port 4280 is used by another add-on	Change the port or stop the conflicting add-on
No log output at all	Add-on crashed immediately	Try reinstalling the add-on

---

#White screen when opening via HA sidebar

This is a known limitation. The ntfy web app uses absolute asset paths that are incompatible with HA Ingress.

Fix: Always use the direct URL:

http://homeassistant.local:4280

See Known-Limitations for details.

---

#Can't log in to the web UI

Symptom	Cause	Fix
Wrong username or password	Credentials incorrect	Double-check admin_username/admin_password in config
Login page not shown	enable_login: false	Set enable_login: true in config and restart
403 Forbidden	User doesn't have admin role	Verify the user was created as admin via admin_username config

---

#Admin Panel login fails

Error	Cause	Fix
Wrong credentials	Wrong username or password	Use the same credentials as the ntfy web UI
Not an admin account	User has user role, not admin	Create the account via admin_username config
Connection failed	Wrong server URL	Use http://homeassistant.local:4280 (port 4280, not 4281)

---

#hijacked connection in the logs

This is harmless. It appears when a client (ntfy app, browser) drops a WebSocket or SSE connection. No action needed.

To reduce the frequency, increase keepalive_interval:

keepalive_interval: "90s"

---

#ntfy HA integration error: "two or more values in the same group of exclusion 'credentials'"

This happens when you fill in both the password and token fields in the HA integration setup.

Fix: Use only one — either password or token. Leave the other field empty.

---

#404 manifest.webmanifest in logs

Harmless. This is an artifact of the HA Ingress proxy requesting the web app manifest. ntfy serves it at the root path which Ingress doesn't forward correctly. No action needed.

---

#Notifications not arriving on phone

1. Confirm the ntfy app is subscribed to the correct topic on the correct server
2. Send a test message from the Admin Panel → Send tab
3. Check if the message appears in the ntfy web UI — if yes, the server is working and the issue is with the app/subscription
4. For iOS: confirm iOS Push is configured correctly

---

#Attachments not working

Attachments require base_url to be set. Without it, the attachment storage is disabled.

base_url: "https://ntfy.your-domain.com"

---

#Version shows ? in Admin Panel Dashboard

This is normal if you're running ntfy older than v2.17.0. The /v1/version endpoint was added in v2.17.0. The current add-on uses v2.17.0 so this should not occur.

---

#Still stuck?

1. Set log_level: DEBUG in the configuration and restart
2. Check the full log output
3. Open an issue on Codeberg with the relevant log lines

#ntfy Web UI — White Screen via HA Sidebar

Symptom: Clicking the add-on in the HA sidebar shows a white/blank screen.

Cause: ntfy's web app is a React Single-Page Application that loads all assets using absolute paths (e.g. /static/js/app.js). When served through HA Ingress, the browser requests these assets from the HA root path instead of the ntfy path — resulting in 404 errors and a broken app.

Workaround: Always access ntfy directly:

http://homeassistant.local:4280

Fix status: Cannot be fixed in this add-on without a change in ntfy upstream to support a configurable base-path. This is a known ntfy issue.

---

#Token List Not Available in Admin Panel

Symptom: The Tokens tab in the Admin Panel cannot display existing tokens.

Cause: The token listing API (GET /v1/account/token) is a user-scoped endpoint that requires the request to come from the same origin as the server. The admin panel runs on port 4281 while ntfy is on port 4280 — the browser blocks the cross-origin request for security reasons.

Workaround: To view or delete tokens, use the ntfy web UI:

http://homeassistant.local:4280 → Account → Access Tokens

Fix status: Would require either a dedicated admin token endpoint in ntfy, or serving the admin panel from the same port as ntfy (which would require significant architectural changes).

---

#Cannot Change User Roles via Admin Panel

Symptom: There is no "Change Role" button in the user table.

Cause: The ntfy v2 REST API (PUT /v1/users) only creates new users. It rejects the request if the user already exists. There is no dedicated endpoint for updating the role of an existing user.

Workaround:

• To promote a user to admin: set admin_username in the add-on config to their username, restart → the account gets the admin role.
• To demote an admin to user: delete and recreate the account as a regular user.

---

#Cannot Delete or Modify Admin Accounts via API

Symptom: Delete and Change Password buttons are hidden for admin accounts.

Cause: The ntfy API returns 401 unauthorized: can only remove regular users from API when attempting to delete or modify admin accounts. This is a deliberate security restriction in ntfy.

Workaround: Admin accounts can only be managed via the add-on configuration (admin_username / admin_password). Change the config and restart to update the admin password.

---

#Only One Admin Account in Config

Symptom: There is only one admin_username / admin_password field in the configuration.

Cause: To keep the config simple, we support bootstrapping one admin at a time.

Workaround: To create multiple admin accounts, change admin_username to the second admin, restart, then set it back and restart again. See Configuration for step-by-step instructions.

---

#No Multi-Architecture Support for armhf / armv7 / i386

The add-on only supports amd64 and aarch64. Home Assistant has dropped official support for armhf, armv7 and i386 hardware. If you are running one of these architectures, it is recommended to migrate to a supported platform.

Here are the current CLI limitations in our add-on and whether they're fixable:

---

1. No interactive CLI access for the user The add-on has no shell or terminal exposed. You have to go through docker exec via the HA SSH add-on every time. It's clunky and not documented anywhere visible. → Fixable: We could add a small shell script wrapper or a button in the admin panel that generates the correct docker exec command pre-filled with the container ID.

---

2. NTFY_AUTH_FILE must be set manually every time The CLI doesn't auto-detect the database path — if you forget export NTFY_AUTH_FILE=/data/ntfy/user.db every command silently fails or errors. → Fixable: Could be solved by adding a shell profile (/etc/profile.d/ntfy.sh) inside the container that exports it automatically on login. One line in the Dockerfile.

---

3. No token auto-provisioning Tokens for HA rest_commands have to be created manually via CLI or Web UI after every fresh install. If the database resets, the token is gone and HA automations break silently with 403. → Fixable: We could generate a fixed HA token at startup in run.sh (same way we create the admin user), log it once, and optionally write it to a known file in /data/ntfy/.

---

4. Password input is interactive ntfy user add and ntfy user change-pass prompt for a password interactively. In scripts you have to pass NTFY_PASSWORD=... as an env var — that's not obvious and not documented for users. → Already partially solved in our run.sh via NTFY_PASSWORD env var for the admin bootstrap. But not documented anywhere for manual use.

---

5. No ACL management in the admin panel Topic-level access control (ntfy access) is entirely CLI-only — there's no UI for it, not even in the official ntfy Web UI. → Fixable in our admin panel: We could add an ACL section that calls the ntfy API to read and write access rules. Would be a meaningful addition over Farmer Ed's setup.

---

Summary — what's worth fixing:

Limitation	Fix effort	Impact
Token auto-provisioning at startup	Low — few lines in run.sh	High — prevents 403 after reinstall
Auto-set NTFY_AUTH_FILE in container profile	Very low — one Dockerfile line	Medium
ACL management in admin panel	Medium	High — currently CLI-only
Interactive password annoyance	Already solved internally	Low

Disclaimer

This is an unofficial, community-maintained Home Assistant add-on wrapper for binwiederhier/ntfy. It is not affiliated with or endorsed by the ntfy project maintainer.

Wrapper License

MIT License

The ntfy server itself is dual-licensed under Apache 2.0 and GPLv2 by its upstream author.

Useful Links