node package manager



Bouncer is a simple router that uses MDNS and substack's bouncy to magically discover your apps and services to hit and fallback when neccessary.



For bouncy to be useful, you need to redirect a wildcard subdomain to localhost (*.dev.local for example). There are lots of methods to do this, but here is one way for OSX.

(shamelessly borrowed from

  1. install dnsmasq
brew install dnsmasq
  1. copy the example config
cp /usr/local/Cellar/dnsmasq/2.55/dnsmasq.conf.example /usr/local/etc/dnsmasq.conf
  1. edit dnsmasq.conf to include the following

where "com.local" is the domain you want to redirect on, I use dev.local 4. (optional) Add the dnsmasq launchd config (provided by homebrew) to your system. Homebrew tells you how to do this.


  1. install it
npm install -g bouncer
  1. Advertise your services (see below)
  2. run bouncer
bouncer -c /path/to/conf.json

NOTE: defaults to ~/.bouncer.json if no config is passed

See below for config info

Advertising services

Bouncer relies on MDNS (aka. Bounjour, ZeroConf) to discover your services, in order for this to work however, you must create and advertisement for that service


var advertise = require('bouncer').advertise
var options = {secret: "cheesecake"}
app.listen(PORT, advertise("service_name", PORT, options))

See below for list of options


Bouncer uses a json config file to define a secret, a list of services with fallbacks, and other options

sample_config.json (obvs without the comments!)

  // port to listen on
  "port" : 8000,
  // secret to use (match with your advertisement)
  "secret" : "mysecret",
  // OPTIONAL - key used to encrypt
  "key": "123456789123",
  // OPTIONAL - a fallback if no corresponding service is found
  "globalFallback" : "",
  // only bind with local instances of the service, default to false
  "localOnly": false,
  // a hash of service names and the fallback url to use
  "services" : {
    "service1" : "",
    "service2" : "",


the advertise options hash taskes a secret and a key, match to above


If you want to use Bouncer programatically, you can.

var Bouncer = require('bouncer').Bouncer
var bouncer = new Bouncer(opts)

opts takes all the same options as the json config and also a few functions

onServiceUp(mdnsRecord) - fired when a service is registered

onServiceDown(mdnsRecord) - fired when a service is removed

onGlobalFault(request, bouncyInstance, serviceName) - handle global faults

onServiceFault(request, bouncyInstance, serverObj) - handle faults for an individual services, serverObj is {name: "service_name", hosts; [mdnsRecord]}

verifyHost(mdnsRecrd) - return true if you want to accept the service