VGS Satellite

Learn how to use VGS Satellite to integrate with VGS without the need to sign up or visit the dashboard. This application gives an ability to build necessary configuration to integrate your product with VGS from your local environment.

VGS Satellite consists of two parts: UI application for building routes configurations based on HAR files and additional python script for mitmproxy that transforms intercepted requests into JSON-HAR format per request.

With the VGS Satellite you can:

  • trail API request logs in real-time;
  • use mitmproxy to intercept/edit/replay requests;
  • generate HAR-JSON representation of intercepted requests;
  • create a VGS route (inbound/outbound) based on selected request.


An important part of using VGS Satellite is the use of mitmproxy. Mitmproxy - is an interactive man-in-the-middle proxy that gives you an ability to intercept, edit and replay requests sent through it on your local system. VGS satellite repo provides you a script to run along with mitmproxy to dynamically dump request-response HAR in JSON format on your local system. To run mitmproxy with UI and VGS

Satellite script use:

MITM_DIR=/path/to/har/files mitmweb --web-iface -s mitm-requests-json.py

Web UI would start on port 8081 and proxy on port 8080.

For more instructions on how to use mitmproxy please refer to the mitmproxy documentation.

Environment variables

Using VGS Satellite you override some values in environment variables to make your experience more flexible.

General environment variables include:

  • MITM_DIR - directory to save intercepted requests to (for mitmproxy script) and to get HAR requests from (for VGS satellite UI)
  • SATELLITE_PORT - port to run VGS satellite web UI on

These environment variables are available only for docker-compose run of VGS Satellite:

  • PROXY_PORT - port to run mitmproxy on
  • WEB_PORT - port to run mitmproxy web UI on
  • MITM_ARGS - additional mitmproxy args (e.g. - --mode reverse:http://localhost:9998/, empty by default)

Installing and running

You can install and run VGS Satellite via npm package, docker image, or github.

NPM Package

VGS Satellite is available on Node Package Manager. Run it with:

npm install -g yarn
yarn global add @vgs/vgs-satellite
SATELLITE_PORT=1234 MITM_DIR=/tmp/mitm_dir vgs-satellite

You can override SATELLITE_PORT and MITM_DIR, for details see [here](satellite#environment variables).

This approach does not run mitmproxy, it should be run separately as seen here

Docker image

VGS Satellite is available on Quay. Run it using:

docker pull quay.io/verygoodsecurity/vgs-satellite
export SATELLITE_PORT=1234
export MITM_DIR=/tmp/mitm_dir
docker run -e SATELLITE_PORT -e MITM_DIR -v "/tmp/mitm_dir:${MITM_DIR}" -p $SATELLITE_PORT:$SATELLITE_PORT quay.io/verygoodsecurity/vgs-satellite

You can override SATELLITE_PORT and MITM_DIR, for details see here.

This approach does not run mitmproxy, it should be run separately as seen here

Running from github

Sources for VGS Satellite are available on Github. We provided docker-compose configuration to run docker-compose alongside mitmproxy. To run it:

  1. Clone sources
git clone git@github.com:verygoodsecurity/vgs-satellite.git && cd vgs-satellite
  1. Create or use .env file inside the project root. For environment variable nomenclature see here.

  2. Run application

docker-compose up

How to use

This manual of how to use VGS Satellite is assuming that you are running it from docker-compose
  1. Run application. We assume that content of .env file wasn't changed
  1. Run example requests:
curl -H "Content-Type: application/json" -x http://localhost:1230 http://httpbin.org/post -d '{"foo": "bar"}
  1. Open VGS Satellite WEB UI on http://localhost:1234

  2. Wait for your requests to appear or add your HAR file by clicking Upload HAR file(s)

Note: you can find HAR file of your requests in /tmp/mitm-requests

  1. Choose your request from the list
  1. Click the “Secure this payload” button
  1. Check the field you would like to secure and click “Secure this payload”

For additional settings please reference the nomenclature

  1. Download inbound/outbound route configuration

What’s next?

After building your route(s) deploy them to production by logging into the VGS Dashboard and importing via the YAML feature or by using the vgs-cli tool.