boringproxy consists of two kinds of long running processes that act as server and client.

Run it in the shell, with bg/fg, in a tmux session, or configure a system daemon.

It is managed via an administrative web interface.

Command line interface

The command line interface is used to create server and client instances.


The server requires you to pass the domain it will serve. It is invoked with:

./boringproxy server -admin-domain <admin-domain>

-admin-domain - the main domain configured in DNS


boringproxy server -admin-domain

Upon first run a simple text database file boringproxy_db.json with admin credentials will be created and a login link is displayed that looks like:




The client needs to know which server to connect to, a valid combination of user and access token plus a unique name for the current client. You can start it with:

./boringproxy client \
    -server <server> -user <user> -token <token> -client-name <client-name>

-server - the domain of the remote server
-user - username, min. six characters, if not admin
-token - access token to authenticate against the service
-client-name - identifier for the client, used in the interface to distinguish the available tunnel origins


boringproxy client \
    -server \
    -token fKFIjefKDFLEFijKDFJKELJF \
    -client-name demo-client \
    -user demo-user

Web interface

The web interface is used to manage users, access tokens and tunnels.

Access it at https://<FQDN>/ where you will be presented with a prompt for a token, or with the direct login link from above.

Web interface after logging in as admin.


The tunnels pane allows creating and removing tunnels. It provides a way for you to specify the settings of a tunnel:


The tokens pane allows to create and remove tokens for your currently logged in user.
Multiple tokens per user can be issued.
Administrators can manage the tokens of all users.


The users pane allows users with administrative priviledge to add and remove users.


There is an experimental HTTP API, that is being used internally by the web interface. Authentication details and routes will become available when its public interface stabilises.