dev-notify-bridge

Lightweight local HTTP bridge that delivers native desktop notifications for containerized or remote Node.js environments (Docker, WSL). Use dev-notify for direct local Node.js notifications; use dev-notify-bridge when your app runs in an environment that cannot access the host desktop directly.

Table of contents

• Overview
• When to use
• Install
• Quick start
• API
• CLI
• Docker integration examples
• Security & best practices
• Troubleshooting
• Contributing
• License

Overview

dev-notify-bridge is a tiny HTTP server that runs on your host machine and accepts JSON POST requests to trigger native desktop notifications (macOS Notification Center, Windows Toasts, Linux notify-send). It is intentionally minimal, secure by default, and intended for local development only.

A typical flow:

1. Run dev-notify-bridge on your host.
2. From inside a container (or remote environment), POST a notification payload to the bridge.
3. The bridge uses node-notifier to show a native desktop notification.

When to use

• You run your application inside Docker, WSL, or a remote VM and want desktop toasts for events (OTPs, errors, build completion).
• You do not need this in production — it’s explicitly a developer convenience tool.

Note: dev-notify is a separate client-side package that sends notifications directly from local Node.js processes. dev-notify-bridge is the host-side relay used when the app cannot show notifications itself.

Install

Globally (recommended for developer machines):

npm install -g dev-notify-bridge

Or run without installing:

npx dev-notify-bridge

Quick start

Start the bridge (default port 6789):

npx dev-notify-bridge

Start on a custom port:

PORT=5454 npx dev-notify-bridge
# or
npx dev-notify-bridge --port 5454

You should see:

 dev-notify-bridge running at http://localhost:6789
💬 Ready to receive notifications

API

POST /notify

Triggers a native desktop notification.

Request JSON

{
  "title": "string",       // required
  "message": "string",     // required
  "sound": true|false,     // optional, default true
  "wait": true|false       // optional, default false
}

Success response (200)

{
  "success": true,
  "backend": "desktop",
  "response": "Notification delivered",
  "metadata": {
    "hostname": "your-machine",
    "platform": "darwin|win32|linux"
  }
}

Error response (4xx/5xx)

{
  "success": false,
  "backend": "desktop",
  "error": "Error message"
}

Example (curl)

curl -X POST http://localhost:6789/notify \
  -H "Content-Type: application/json" \
  -d '{"title":"Build OK","message":"API built successfully","sound":true}'

CLI

Run the bridge:

npx dev-notify-bridge [--port <port>] [--verbose]

Options:

• --port, -p — server port (default 6789)
• --verbose, -v — enable verbose logging

Environment variable:

• PORT — alternate way to set the port.

Docker integration examples

1. Run a container and allow it to reach the host bridge

docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  my-image

Inside the container, send a notification to the bridge:

// example using axios in container
await axios.post('http://host.docker.internal:6789/notify', {
  title: 'Container Ready',
  message: 'Service listening on :3000'
});

2. docker-compose (env var)

services:
  api:
    build: .
    environment:
      - DEV_NOTIFY_BRIDGE=http://host.docker.internal:6789
    # For Linux hosts that need it:
    # extra_hosts:
    #   - "host.docker.internal:host-gateway"

Using --add-host=host.docker.internal:host-gateway or extra_hosts is recommended for cross-platform resolution.

Security & best practices

• Local-only by default: the server binds to 127.0.0.1 (localhost) for safety. Do not expose it publicly.
• Authentication: intentionally omitted for convenience in local dev. If you must use this across a network, add an auth layer or use SSH port forwarding.
• Production: do not use in production; it is a development tool only.
• Logging: use --verbose to debug notification delivery during setup.

Troubleshooting

• host.docker.internal DNS not found (Linux) Use --add-host=host.docker.internal:host-gateway when running the container, or set DEV_NOTIFY_BRIDGE to the host IP resolved by your environment.

• No notification appears but API responded 200

  • Ensure node-notifier supports your platform (Linux may need notify-send available).
  • Check system notification settings (do-not-disturb, focus assist).
  • Try --verbose to view bridge logs.

• Bridge fails to start (port in use) Start with a different port: PORT=5454 npx dev-notify-bridge.

Contributing

Contributions, issues, and feature requests are welcome.

Suggested workflow:

1. Fork the repo and create a branch.
2. Run npm install and npm run build.
3. Add tests or examples for new behavior.
4. Open a PR with a clear description and motivation.

Please follow standard code style.

License

MIT © 2025