schema_version: 6
publication_status: published
slug: ntfy
name: ntfy
tagline: Private topic-based notifications for scripts and devices
summary: ntfy delivers messages from scripts, monitoring, and home automations to subscribed browsers and mobile clients. This recipe requires login, denies anonymous topic access, stores messages and attachments locally, and provisions an administrator from a private bcrypt entry.
status: active
editorial_status: experimental
links:
  website: https://ntfy.sh/
  source: https://github.com/binwiederhier/ntfy
  documentation: https://docs.ntfy.sh/
  issues: https://github.com/binwiederhier/ntfy/issues
classification:
  categories:
  - Notifications
  tags:
  - notifications
  - push
  - pub-sub
  - automation
  implementation_languages:
  - Go
  - JavaScript
  alternatives_to:
  - Pushover
license:
  spdx: Apache-2.0 OR GPL-2.0-only
  kind: open_source
  restrictions: []
  notes: Upstream is dual licensed under Apache-2.0 and GPLv2; choose the applicable option. The recipe has its own MIT license. Third-party client assets retain their upstream terms.
localization:
  ui_languages:
  - en
  - ru
  docs_languages:
  - en
  - ru
clients:
  web: true
  android: true
  ios: true
  desktop: false
auth:
  oidc: none
  saml: none
  two_factor: none
  proxy_header: false
requirements:
  architectures:
  - amd64
  - arm64
  min_cpu_cores: 1
  min_ram_mb: 128
  recommended_ram_mb: 256
  min_disk_gb: 2
  gpu:
    required: false
    supported: false
  database: sqlite
  dependencies: []
operations:
  install_difficulty: 2
  installation_levels:
    home: supported
    vps: supported
    reliable: unsupported
  maintenance_difficulty: 2
  backup_supported: true
  restore_tested: true
  healthcheck: true
  reverse_proxy_required: false
  update_complexity: in_place
recipe:
  id: ntfy-compose
  version: 2
  compose_file: compose.yaml
  env_example: .env.example
  installation: installation.md
  troubleshooting: troubleshooting.md
  supported_docker_compose: '>=2.24.0'
  application_version: v2.34.0
  images:
  - name: binwiederhier/ntfy
    tag_source: env
  - name: alpine
    tag_source: pinned
  tested_at: '2026-10-25'
  tested_architectures:
    amd64: passed
    arm64: not_tested
  smoke_test: full
  check_history:
  - tested_at: "2026-10-25"
    application_version: v2.34.0
    recipe_version: 2
    tested_architectures:
      amd64: passed
      arm64: not_tested
    smoke_test: full
    restore_tested: true
  - tested_at: "2026-10-24"
    application_version: v2.33.1
    recipe_version: 1
    tested_architectures:
      amd64: passed
      arm64: not_tested
    smoke_test: full
    restore_tested: true
  license: MIT
  smoke_test_limitations:
  - On amd64, the smoke verifies live HTTP delivery, blocked anonymous topic reads/writes and signup, exact attachment bytes, a regular account, token scope through topic ACLs, subscriptions/settings, and recovery after deleting the data volume; arm64 was not tested.
  - Attachment URLs are bearer links and intentionally remain downloadable without login when the URL is known. The test verifies this behavior; it does not establish private or end-to-end encrypted attachments.
  - Browser Web Push, Android/iOS background delivery, Firebase, upstream polling, SMTP, calls, external integrations, TLS proxies, and long-term retention/expiry were not exercised.
security:
  public_exposure: supported
  default_bind: localhost
  privileged: false
  host_network: false
  docker_socket: false
  known_risks:
  - 'Attachment URLs are bearer links: anyone who knows one can download the file without logging in, even if the topic denies anonymous access. Encrypt sensitive attachments before uploading and protect logs containing those links.'
  - Messages, attachments, accounts, tokens, and bcrypt bootstrap hashes remain on the server without end-to-end encryption. Protect the data volume and encrypt off-server backups.
  - The NTFY_AUTH_USERS entry is declarative and overrides stored administrator credentials at startup. Keep it private and consistent during recovery; changing only a saved plaintext password does not rotate this hash.
  - Give automations regular users with explicit topic ACLs instead of administrator tokens. A leaked token inherits its owner's permissions; topic names are not passwords.
  - Cached messages and attachments expire after seven days. Backup restores original timestamps, not a new retention period. Proxy requests share one rate limit while forwarded-IP trust is disabled.
  assessment:
    status: warnings
    assessed_at: '2026-10-24'
upstream:
  release_source: github
  repository: binwiederhier/ntfy
  last_release_at: '2026-10-24'
  last_checked_at: '2026-10-25T15:20:08.621Z'
  stars: 35024
  stars_checked_at: '2026-10-24T08:36:41Z'
  releases_last_year: 25
  releases_checked_at: '2026-10-25T15:20:08.621Z'
update_tracking:
  releases:
    status: current
    checked_at: "2026-10-25T15:20:08.621Z"
    latest_version: v2.34.0
  critical_vulnerabilities:
    status: no_findings
    checked_at: "2026-10-25T15:21:03.910Z"
    critical_count: 0
    scanner: trivy
    ids: []
  breaking_updates:
    status: unknown
    checked_at: null
  compose_changes:
    status: not_tracked
    checked_at: null
  outdated_images:
    status: current
    checked_at: "2026-10-25T15:20:08.621Z"
    images: []
update_policy:
  images:
  - image: binwiederhier/ntfy
    provider: docker_hub
    repository: binwiederhier/ntfy
  compose: null
content:
  description: description.md
  logo: assets/logo.svg
  screenshots:
  - file: assets/notifications.webp
    alt: ntfy inbox showing realistic household notifications across three subscribed topics
  - file: assets/topic.webp
    alt: ntfy backup topic with recovery messages and a sample attachment in dark mode
  - file: assets/account.webp
    alt: ntfy regular account with separately named automation access tokens
  updated_at: '2026-10-25'