the fast, reliable localhost tunneling solution Man Page (v1.0.0.190225)

2019-02-25, 12:16


pagekite - Make localhost servers publicly visible


pagekite [--options] [service] kite-name [+flags]


PageKite is a system for exposing localhost servers to the public Internet. It is most commonly used to make local web servers or SSH servers publicly visible, although almost any TCP-based protocol can work if the client knows how to use an HTTP proxy.

PageKite uses a combination of tunnels and reverse proxies to compensate for the fact that localhost usually does not have a public IP address and is often subject to adverse network conditions, including aggressive firewalls and multiple layers of NAT.

This program implements both ends of the tunnel: the local "back-end" and the remote "front-end" reverse-proxy relay. For convenience, pagekite also includes a basic HTTP server for quickly exposing files and directories to the World Wide Web for casual sharing and collaboration.

Basic usage

Basic usage, gives `http://localhost:80/` a public name:
$ pagekite

To expose specific folders, files or use alternate local ports:
$ pagekite /a/path/ +indexes  # built-in HTTPD
$ pagekite *.html           # built-in HTTPD
$ pagekite 3000           # HTTPD on 3000

To expose multiple local servers (SSH and HTTP):
$ pagekite ssh:// AND 3000

Services and kites

The most comman usage of pagekite is as a back-end, where it is used to expose local services to the outside world.

Examples of services are: a local HTTP server, a local SSH server, a folder or a file.

A service is exposed by describing it on the command line, along with the desired public kite name. If a kite name is requested which does not already exist in the configuration file and program is run interactively, the user will be prompted and given the option of signing up and/or creating a new kite using the service.

Multiple services and kites can be specified on a single command-line, separated by the word 'AND' (note capital letters are required). This may cause problems if you have many files and folders by that name, but that should be relatively rare. :-)

Kite configuration

The options --list, --add, --disable and --remove can be used to manipulate the kites and service definitions in your configuration file, if you prefer not to edit it by hand. Examples:

Adding new kites
$ pagekite --add /a/path/ +indexes
$ pagekite --add 80

To display the current configuration
$ pagekite --list

Disable or delete kites (--add re-enables)
$ pagekite --disable
$ pagekite --remove


Flags are used to tune the behavior of a particular kite, for example by enabling access controls or specific features of the built-in HTTP server.

Common flags

HTTP protocol flags

Built-in HTTPD flags


The full power of pagekite lies in the numerous options which can be specified on the command line or in a configuration file (see below).

Note that many options, especially the service and domain definitions, are additive and if given multiple options the program will attempt to obey them all. Options are processed in order and if they are not additive then the last option will override all preceding ones.

Although pagekite accepts a great many options, most of the time the program defaults will Just Work.

Common options

Back-end options

Front-end options

System options

Configuration files

If you are using pagekite as a command-line utility, it will load its configuration from a file in your home directory. The file is named .pagekite.rc on Unix systems (including Mac OS X), or pagekite.cfg on Windows.

If you are using pagekite as a system-daemon which starts up when your computer boots, it is generally configured to load settings from /etc/pagekite.d/*.rc (in lexicographical order).

In both cases, the configuration files contain one or more of the same options as are used on the command line, with the difference that at most one option may be present on each line, and the parser is more tolerant of white-space. The leading '--' may also be omitted for readability and blank lines and lines beginning with '#' are treated as comments.

NOTE: When using -o, --optfile or --optdir on the command line, it is advisable to use --clean to suppress the default configuration.


Please keep in mind, that whenever exposing a server to the public Internet, it is important to think about security. Hacked webservers are frequently abused as part of virus, spam or phishing campaigns and in some cases security breaches can compromise the entire operating system.

Some advice:

   * Switch PageKite off when not using it.
   * Use the built-in access controls and SSL encryption.
   * Leave the firewall enabled unless you have good reason not to.
   * Make sure you use good passwords everywhere.
   * Static content is very hard to hack!
   * Always, always make frequent backups of any important work.

Note that as of version 0.5, pagekite includes a very basic request firewall, which attempts to prevent access to phpMyAdmin and other sensitive systems. If it gets in your way, the +insecure flag or --insecure option can be used to turn it off.

For more, please visit:

Tunnel Request Authentication

When running pagekite as a front-end relay, you can enable dynamic authentication of incoming tunnel requests in two ways.

One uses a DNS-based protocol for delegating authentication to a remote server. The nice thing about this, is relays can be deployed without any direct access to your user account databases - in particular, a zero-knowlege challenge/response protocol is used which means the relay never sees the shared secret used to authenticate the kite.

The second method delegates authentication to an external app; this external app can be written in any language you like, as long as it implements the following command-line arguments:

  --capabilities     Print a list of capabilities to STDOUT and exit
  --server           Run as a "server", reading queries on STDIN and
                  sending one-line replies to STDOUT.
  --auth     Return JSON formatted auth and quota details
  --zk-auth   Implement the DNS-based zero-knowlege protocol
The recognized capabilities are SERVER, ZK-AUTH and AUTH. One of AUTH or ZK-AUTH is required.

The JSON --auth responses should be dictionaries which have at least one element, secret or error. The secret is the shared secret to be used to authenticate the tunnel. The dictionary may also contain advisory quota values (quota_kb, quota_days and quota_conns), and IP rate limiting parameters (ips_per_sec-ips and ips_per_sec-secs).

The source distribution of pagekite includes a script named which implements this protocol.


Using pagekite as a front-end relay with the native Python SSL module may result in poor performance. Please use the pyOpenSSL wrappers instead.

See Also



- Bjarni R. Einarsson 
- The Beanstalks Project ehf. 
- The Rannis Technology Development Fund 
- Joar Wandborg 
- Luc-Pierre Terral

Copyright and license

Copyright 2010-2019, the Beanstalks Project ehf. and Bjarni R. Einarsson.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see:




We accept Bitcoin at: