Awesome Open Source
Awesome Open Source



hiproxy is a lightweight web proxy tool based on Node.js. The primary purpose of hiproxy is to solve the problem of host management and reverse proxy needs of developers.

For example, if you are working as a team and each of the developers in the team need a different proxy setting, you will no longer need to modify your hosts file or use a web server like Nginx as a reverse proxy.

hiproxy extends the syntax of hosts file to support port numbers. Besides, hiproxy also supports configuration through a syntax similar to the Nginx configuration file.


Build Status Build status codecov js-semistandard-style npm Node.js version license

Why Hiproxy?

If you are a front-end developer, it is not uncommon for you to encounter the following problems:

Debugging web pages locally: To develop your web projects in a local development environment, you’ll have to run a back-end server (such as a Node.js express application, or a Java SpringBoot application). As a front-end developer, you might not be familiar with the back-end technology stack, simply setting up the development environment can consume a lot of your time.

Cross-Origin Issues: While developing your front-end projects locally, you might need to solve cross-domain and cross-origin resource sharing issues. To address these problems, you will need to modify the response header.

Self-Signed Certificates: You’ll often need to test https pages. When you visit https pages with a self-signed certificate, your browser will raise security warnings.

One common way to modify the response header is to put a proxy as a “man in the middle”. NGINX, for example, has a nice syntax that you can configure as a reverse-proxy to handle all these needs.

Although NGINX is a great tool to address all the above problems, when setting up NGINX, you’ll also modify your hosts file a lot to proxy the requests to a local NGINX service. This can especially turn out to be a burden if you are working on multiple projects.

Can we have a better way to solve this problem?

Well, yes. Meet hiproxy!


  • Nginx.config-style configuration file syntax with a simple and intuitive configuration
  • Extended hosts configuration with port numbers.
  • Plugin extensions to rewrite directives, command line interface, and pages
  • Automatic generation and management of TLS certificates
  • Auto-detection of configuration file
  • Proxy auto-configuration
  • You can run hiproxy as a background service and redirect its output to a log file.
  • You can open a browser window and configure your proxy from its web interface.
  • hiproxy provides a Node.js API for fine-tuning and lower-level control.


npm install -g hiproxy

If you want to experience the latest features of hiproxy, you can install the next version.

npm install -g [email protected]



Start proxy server:

hiproxy start -p 5525 --debug --workspace ${PATH_TO_WORKSPACE}

Configure proxy:

CLI Usage

> hiproxy --help


    hiproxy [command] [option]


  start    Start a local proxy server
  stop     Stop the local proxy server (Only works in daemon mode)
  restart  Restart the local proxy service (Only works in daemon mode)
  state    Show all the servers state (Only works in daemon mode)
  open     Open browser and set proxy
  hello    A test command that say hello to you.


  -v, --version     Display version information
  -h, --help        Display help information
  --log-dir <dir>   The log directory when run in background, default: user home directory
  --log-time        Show time info before every log message
  --log-level       The log levels, format: <level1>[,<lavel2[,...]]
  --grep <content>  Filter the log data


Note: This is an incomplete documentation, we are still writing, if you are willing to help us write or translate the documentation, please contact [email protected]

Steps for Contributing Documentation

After you have submitted your pull request, we'll try to get back to you as soon as possible. We may suggest some changes or improvements.  


Node.js API

var Server = require('hiproxy').Server;
var proxy = new Server(8848, 10086);

// events
proxy.on('request', function(req, res){
  req.someThing = 'some thing';
  console.log('new request =>', req.method, req.url);

proxy.on('data', function(data){
  console.log('on response =>', data.toString());

proxy.start().then(function (servers) {
  console.log('proxy server started at:');

// stop proxy server
// proxy.stop();

// restart proxy server
// proxy.restart();

Hosts Configuration Example

hiproxy supports enhanced version of hosts, the hosts file supports not only IP but also port numbers.

# comment

Rewrite Configuration Example

set $port 8899;
set $ip;
set $online;

domain {
  location / {
    proxy_pass http://$online/;

  location /blog/ {
    proxy_pass http://$ip:$port/blog/;

    proxy_set_header from 'hiproxy';

    set_header proxy 'hiproxy';

Sample Project

Here is an example project that you can play with.

Running Tests

npm test


Please read for details on our code of conduct, and the process for submitting pull requests to us.


  • zdying - HTML/JavaScript/CSS/Node.js developer zdying
  • zhouhailong - HTML/JavaScript/CSS/Node.js developer zhouhailong
  • Alfred Sang (aka i5ting) - a full-stack developer and Node.js evangelist. He works for Alibaba Group as a Principal Front-End Developer and runs a self-media on the topic of Full-stack Node.js. His book “The Marvelous Node.js” (Part I) was published in July 2019.._

See also the list of contributors who participated in this project.

Built With

  • hemsl - a lightweight Node.js command line argv parser and command executor.
  • colors - get color and style in your node.js console.
  • node-forge - JavaScript implementations of network transports, cryptography, ciphers, PKI, message digests, and various utilities.
  • op-browser - Open browser window and set proxy.
  • os-homedir - Node.js 4 os.homedir() ponyfill.
  • url-pattern - easier than regex string matching patterns for urls and other strings. turn strings into data or data into strings.
  • simple-mime - A simple mime database.

Thanks to the authors of the above libraries to provide such a useful library.

Thanks To

Thanks to the above friends to help translate hiproxy documents.

Change Log

See the for details.


This project is licensed under the MIT License - see the LICENSE file for details

Code of Conduct

We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

See the code of conduct for details.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,538,553
Nodejs (55,471
Http (5,720
Nginx (5,227
Proxy (3,512
Https (1,113
Certificate (912
Reverse Proxy (591
Hosts (412
Rewrite (85
Related Projects