Tunnel proxy package in Go
Switch branches/tags
Nothing to show
Clone or download
cihangir Merge pull request #43 from rjeczalik/hijack-error
server: log writer type on hijack feature check failure
Latest commit 35a8b95 Jun 2, 2017


Tunnel GoDoc Go Report Card Build Status

Tunnel is a server/client package that enables to proxy public connections to your local machine over a tunnel connection from the local machine to the public server. What this means is, you can share your localhost even if it doesn't have a Public IP or if it's not reachable from outside.

It uses the excellent yamux package to multiplex connections between server and client.

The project is under active development, please vendor it if you want to use it.


The tunnel package consists of two parts. The server and the client.

Server is the public facing part. It's type that satisfies the http.Handler. So it's easily pluggable into existing servers.

Let assume that you setup your DNS service so all *.example.com domains route to your server at the public IP Let us first create the server part:

package main

import (


func main() {
	cfg := &tunnel.ServerConfig{}
	server, _ := tunnel.NewServer(cfg)
	server.AddHost("sub.example.com", "1234")
	http.ListenAndServe(":80", server)

Once you create the server, you just plug it into your server. The only detail here is to map a virtualhost to a secret token. The secret token is the only part that needs to be known for the client side.

Let us now create the client side part:

package main

import "github.com/koding/tunnel"

func main() {
	cfg := &tunnel.ClientConfig{
		Identifier: "1234",
		ServerAddr: "",

	client, err := tunnel.NewClient(cfg)
	if err != nil {


The Start() method is by default blocking. As you see you, we just passed the server address and the secret token.

Now whenever someone hit sub.example.com, the request will be proxied to the machine where client is running and hit the local server running (assuming there is one). If someone hits sub.example.com:3000 (assume your server is running at this port), it'll be routed to

That's it.

There are many options that can be changed, such as a static local address for your client. Have alook at the documentation


The server/client protocol is written in the spec.md file. Please have a look for more detail.


The BSD 3-Clause License - see LICENSE for more details