Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

hostkeeper (WIP)

Current tag Repository issues Flattr this repository

hostkeeper is a Vagrant box that comes with a DNS server (dnsmasq) and a web interface to provide an easy way to manage network-wide DNS emulations (or modifications) during local web development phases. Usually you need to adjust the /etc/hosts file on your OS X or Windows machine to test your local project with productive domains. However, this approach won't work on a (non jailbreaked) iPhone which has no direct file system access. Once the DNS in your network settings is set to the IP of the hostkeeper Vagrant box, all DNS requests from said device will obey the "faked" ones from hostkeeper, hence you can surf via Safari to "" but don't end up on the productive web server of Instead you end up on your local development box, since you added a mapping for that in the hostkeeper web interface.


Using Vagrant (recommended)

  1. Make sure you've installed Vagrant
  2. Clone this repository:
    git clone
  3. Boot up the Vagrant box using:
    cd hostkeeper
    vagrant up
  4. Grab a coffee and wait about 6-7 minutes until hostkeeper has finished setting everything up. Keep an eye on the Vagrant provisioning script, it'll let you know as soon as it's done.
  5. Once completed, add your desired host/IP mappings in the hostkeeper web interface: (The guest system tries to setup an bridged network interface of your primary interface)
  6. Setup as DNS server on any device where you want to use the adjusted/dummy/fake hostnames.

Without Vagrant

1. Prepare DNS (dnsmasq)
  1. Make sure you've installed dnsmasq

  2. Clone this repository:
    git clone /opt/hostkeeper

  3. Adjust your dnsmasq configuration (/etc/dnsmasq.conf) so it'll load our hosts file:

  4. Restart dnsmasq to activate the new configuration:
    service dnsmasq restart

2. Web interface
  1. Make sure you've installed grunt-cli and bower globally:
    npm install -g grunt-cli bower
  2. Install all Node dependencies in the public/ directory:
    cd /opt/hostkeeper
    npm install
  3. Install all libraries using Bower:
    bower install
  4. Run Grunt tasks to compile assets:
3. RESTful API
  1. Copy default host database into project root:
    cp /opt/hostkeeper/vagrant-opt/db.example.json /opt/hostkeeper/db.json
  2. Create folders for pid and log files:
    mkdir -p /opt/hostkeeper/pid /opt/hostkeeper/log
  3. Run app.js to start web and API server (as root - if your dnsmasq runs as root):
    sudo node app.js
  4. Open the hostkeeper web interface and add some mappings:

To test the functionality, you can directly query your local DNS server by running:

$ dig @[hostkeeper] +short

As you can see, hostkeeper returns our adjusted (example) web server IP:


Install/setup/boot hostkeeper

$ vagrant up

In case you want to see stdout output of the commands running in the background:

$ HOSTKEEPER_DEBUG=true vagrant up

Recompile assets/node modules/bower components

In case you contribute and want to test your changes:

$ vagrant provision

Again, in case you want to see stdout output of the commands running in the background:

$ HOSTKEEPER_DEBUG=true vagrant up

Shutdown virtual machine

$ vagrant suspend

And if you want to power it up again:

Remove virtual machine

$ vagrant destroy


hostkeeper consists out of three parts:


  • Heart of the hostkeeper project
  • Returns "modified" DNS requests for all clients

Web interface

  • Easy panel for users to add host/IP mappings
  • Communicates via REST API to rebuild dnsmasq hosts files and restart services
  • ExpressJS as static web server


  • REST using simple-node-router
  • Maintains the hosts database/storage
  • Turns database/storage into dnsmasq-compatible format
  • Restarts dnsmasq to reload new hosts

You can find a detailed API documentation here:

Requirements / Dependencies

Using Vagrant

  • Vagrant

Without Vagrant

  • NodeJS
  • Grunt
  • Bower
  • dnsmasq




  1. Fork it
  2. Create your feature branch: git checkout -b feature/my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin feature/my-new-feature
  5. Submit a pull request




💻 Vagrant box that comes with a DNS server and a web interface to manage LAN-wide /etc/hosts-modifications







No packages published