Maintain a TLD on localhost for all your projects
JavaScript Shell
Switch branches/tags
Nothing to show
Clone or download
Latest commit 2205309 Dec 30, 2014

Local TLD

Build Status Dependency Status devDependency Status

Local TLD maintains a local development top level domain that you can hook various projects into.

If you know pow, this is pow without the Rack part.

Mac OS X only, for the time being. Cross platform support desired, if you can contribute it! :)

Er what?

Here’s an example. What if you maintained two web projects A and B and have a local setup of both, and you’d like to work on them both at the same time, or switch easily, and you don’t want to mess with things like http://localhost:8888 because that is just annoying and ugly.

What if you could have these two nice addresses:

Yes, you can do that by messing with /etc/hosts, but it ain’t pretty, and you have to do it for every new project and it is ugly.


$ npm -g install local-tld
  # or for now git clone $thisrepo
$ $EDITOR ~/.local-tld.json
  "8000": {
    "name": "myfancyprojectA"
  "8001": {
    "name": "thatotherprojectB"

Dat it. ~/.local-tld.json maps the a subdomain to a TCP port. So if you have an httpd running on localhost:8000 you can now reach it by going to

I want my app to register itself with local-tld!


Ok cool, how does it work?

This uses a cool dynamic DNS system that is built into Mac OS X. Local TLD runs a minimal DNS lookup server that does the address translation magic.

I want subdomains!

Easy. Just make your configuration look like this:

  "8000": {
    "name": "myfancyprojectA",
    "aliases": ["subdomain1", "subdomain2"]

Now, you should be able to reach localhost:8000 from,, and!

Sweet. Does it work with boot2docker ports?

Yep! In addition to the port, you'll need to specify your boot2docker ip address (usually for the domains you want to map:

  "": {
    "name": "myfancyprojectC"

(Astute readers will note that this actually means it works with any server on any IP address, not just boot2docker)

No Original Work

This is all ripped out of pow, we don’t claim any credit.


Apache 2 License


(c) 2013 Jan Lehnardt