DEV Community

Sitota Alemu
Sitota Alemu

Posted on

Using dev-notify-bridge to Get Desktop Notifications from Docker or Remote Environments

#tooling #node #productivity #docker

Using dev-notify-bridge to Get Desktop Notifications from Docker, WSL, or Remote Environments

Instantly see OTPs, build results, and app notifications — even from inside Docker or WSL.

When running Node.js apps in Docker, WSL, or remote environments, desktop notifications simply don’t work. Your app can’t access the host system’s notification center — meaning no popups for build completions, test results, or verification codes.

This is especially frustrating during local authentication testing, when you need to check OTPs or verification codes sent by their app. Instead of instantly seeing the code, you often switch between tools like Mailtrap or database viewers — an unnecessary delay that breaks development flow.

dev-notify-bridge solves this problem by acting as a local HTTP listener on your host machine. Any containerized or remote app can send a POST request to it, and the bridge instantly triggers a native desktop notification on your computer.

It’s lightweight, cross-platform, and designed purely for local development, making it perfect for things like:

  • OTP and verification code previews
  • Build complete or test result notifications
  • Background job or deployment status updates

Install

Install globally:

npm install -g dev-notify-bridge
Enter fullscreen mode Exit fullscreen mode

Or just run it on the fly:

npx dev-notify-bridge
Enter fullscreen mode Exit fullscreen mode

By default, it listens on port 6789.

Run the bridge

Start the bridge on your host machine:

npx dev-notify-bridge
Enter fullscreen mode Exit fullscreen mode

To change the port:

npx dev-notify-bridge --port 5454
Enter fullscreen mode Exit fullscreen mode

You’ll see a message like:

 [ dev-notify-bridge ] running at http://localhost:5454
Enter fullscreen mode Exit fullscreen mode

That means it’s ready to receive notification requests.

Sending notifications from a container or remote app

Once the bridge is running locally, your Docker container or remote service can send a POST request to it.

When using a single container

If you’re running your app using docker run, add the following flag so your container can reach the host machine:

--add-host=host.docker.internal:host-gateway
Enter fullscreen mode Exit fullscreen mode

Then send a POST request from inside your container:

curl -X POST http://host.docker.internal:5454/notify \
  -H "Content-Type: application/json" \
  -d '{"title": "Build Complete", "message": "Your backend is ready", "sound": true}'
Enter fullscreen mode Exit fullscreen mode

You should instantly see a desktop notification pop up.

When using Docker Compose

If you’re running multiple services through docker-compose, make sure each service that needs to send notifications includes an extra_hosts entry:

services:
  my-api:
    build: .
    extra_hosts:
      - "host.docker.internal:host-gateway"
Enter fullscreen mode Exit fullscreen mode

This ensures the container can resolve host.docker.internal correctly, especially on Linux systems.

On macOS and Windows, Docker Desktop already provides host.docker.internal by default,
but keeping this config ensures your setup stays portable across all platforms.

So whether your team is using Linux, macOS, or Windows — notifications will just work.

Example with JavaScript

Here’s how you can trigger a notification from your app code:

import axios from 'axios';

await axios.post('http://host.docker.internal:5454/notify', {
  title: 'Server Started',
  message: 'API is running on port 3000',
  sound: true
});
Enter fullscreen mode Exit fullscreen mode

Common issues

No notification appears
Check that notifications are enabled on your system and that you’re not in “Do Not Disturb” mode.
On Linux, make sure the notify-send utility is installed.

DNS not resolving (Linux users)
If you get ENOTFOUND host.docker.internal, add the flag
--add-host=host.docker.internal:host-gateway (for single containers)
or use the extra_hosts section (for Docker Compose).

Port already in use
You can change the port using --port, e.g. npx dev-notify-bridge --port 6000.

Why use it

dev-notify-bridge exists to make your development flow smoother.
No need to tail logs or wait for builds — get instant, native desktop notifications from apps running anywhere, even in isolated environments.

It’s tiny, fast, cross-platform, and takes just one command to start.

Quick Docker Setup Examples

Below are minimal examples to get you started, whether you’re using a single container or a multi-service setup.

Single Container (e.g. development API) 

docker run -d \
  --name my-api \
  --add-host=host.docker.internal:host-gateway \
  -e NODE_ENV=development \
  -p 3000:3000 \
  my-api-image
Enter fullscreen mode Exit fullscreen mode

Then, inside your app:

await axios.post('http://host.docker.internal:5454/notify', {
  title: 'Build Complete',
  message: 'API container is up',
});
Enter fullscreen mode Exit fullscreen mode

Multi-Service (docker-compose.yml) 

version: '3.9'
services:
  service-name:
    build: .
    volumes:
      - .:/usr/src/app
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      NODE_ENV: development
    command: npm run dev
Enter fullscreen mode Exit fullscreen mode

Once your services are running, any container can send notifications to the bridge running on your host system.

That’s all it takes.

Run dev-notify-bridge once on your host machine, and your Docker or remote apps can instantly trigger native desktop notifications — no extra setup, no manual checking.

No more switching to Mailtrap or database tools just to read an OTP.
No more tailing logs to see if a build finished.
Just instant feedback, right where you need it — on your desktop.

It’s small, fast, and made to keep developers in flow, even when code runs in isolated environments.

Top comments (0)