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

#Pages

#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

#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://github.com/pol4rfuchs/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

#General

#Authentication & Access

#Cache & Performance

#Attachments

Attachments require base_url to be set.

#iOS Push Notifications

See iOS-Push-Notifications for details.

#Admin Panel

The built-in admin panel (port 4281) has been removed from this add-on. Its functionality — user/token management, dashboard, send tests — now lives in the separate ntfy_manager add-on. Install that add-on if you want a web-based admin console.

#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: true
cache_duration: "12h"
attachment_file_size_limit: "15M"
attachment_total_size_limit: "5G"
attachment_expiry_duration: "3h"
keepalive_interval: "45s"
message_size_limit: "4096"
visitor_message_daily_limit: 1000000
upstream_base_url: "https://ntfy.sh"
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. Web-Based Admin Console (Optional)

The built-in admin panel was removed from this add-on. If you want a web UI for managing users, tokens and sending test messages, install the separate ntfy_manager add-on and point it at this ntfy server.

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 ntfy_manager add-on's Tokens tab — see Admin Panel.

#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

#Tags (Emoji Shortcodes)

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

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

Removed. The built-in admin panel (port 4281) was removed from the ntfy add-on. Its Dashboard, Users, Tokens, Send and Info tabs now live in the separate ntfy_manager add-on, which talks to this ntfy server over its API. Install and configure ntfy_manager if you need a web-based admin console — see its wiki page for the full walkthrough.

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.

#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

#Token Management

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

#Access Control (ACL)

#Publish (CLI)

#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:

#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

#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 via the ntfy web UI, curl, or the ntfy_manager add-on's Send tab — see Admin Panel
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"

#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.

#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.

#ntfy CLI Requires Container Access

There is no shell or terminal exposed by the add-on itself. CLI commands (user/token/ACL management) require docker exec via the HA SSH add-on, and NTFY_AUTH_FILE=/data/ntfy/user.db must be exported manually in each session. See CLI Reference for the exact commands.

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