This add-on is operated by DeltaVersion LLC

Reliable Static Dedicated IP Address for Outbound Traffic

Last updated February 20, 2025

NScriptio is an add-on that provides Heroku applications the ability to proxy their app network output through HTTP/HTTPS proxy under a pair of fixed, static IP. NScriptio is language and framework agnostic.

NScriptio acts as a proxy for outbound traffic, tunneling your requests through a pair of balanced IP addresses. You can use given addresses anywhere you need a fixed IP: API providers, firewall configurations, etc.

Provisioning the Add-on

Add the Nscriptio add-on to a Heroku application via the CLI:

$ heroku addons:create nscriptiod --app your-app-name -- --cc=ca
-----> Creating nscriptiod on ⬢ your-app-name... free
       Your add-on is being provisioned, will be available shortly
       nscriptiod-graceful-83372 is being created in the background. The app will restart when complete...
       Use heroku addons:info nscriptiod-graceful-83372 to check creation progress
       Use heroku addons:docs nscriptiod to view documentation

Use the cc option to specify a country you want your IPs to be in. If not provided, the default is us. We provide IPs from following locations:

If you want more locations, just ask us at support@nscriptio.com.

After adding the add-on, the NSCRIPTIOD_HTTP, NSCRIPTIOD_HTTPS config vars are available in the app. You can retrieve them by using the heroku config:get command:

$ heroku config:get --app your-app-name NSCRIPTIOD_HTTPS
https://username:password@nscriptio.online:3128

Add-on Dashboard

Access the dashboard via the CLI:

heroku addon:open nscriptiod

or by visiting the Heroku apps web interface and selection the application in question, then select NScriptio from the add-ons menu.

What are my IPs?

The add-on provides two static IP addresses with fallback capability. Traffic routes through your primary IP, but if it fails, it uses the fallback IP. Both IPs are listed on the add-on dashboard

Local Setup

Environment Setup

To use NScriptio to proxy requests while developing locally, you can exportNSCRIPTIOD_* environment variables to a config file for use in other applications:

$ heroku config:get --app your-app-name NSCRIPTIOD_HTTPS -s  >> .env
$ heroku config:get --app your-app-name NSCRIPTIOD_HTTP -s  >> .env

You can either use the .env file within other application as an ENV import, or use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file.

For more information, see the Heroku Local article.

Use with global proxy wrapper

We provides a proxy wrapper to minimize code change to existing applications, with it you don’t need to make any changes to your source code(only Procfile), this tool will work in too modes:

• Global Mode: forces any TCP connection made by the application to follow through proxy
• TCP Tunnel Mode: tunnel single TCP connection through proxy, this mode works for any application (databases)

Installing the wrapper

cd ~/my-awesome-app
curl https://gitlab.com/api/v4/projects/66079955/packages/generic/nscriptio/1.0.0/nscriptio.tar.gz | tar xz
git add bin
git commit -m "add nscriptio wrapper"

Global Mode

Modify your Procfile to prepend bin/nscriptio to any command whose connections you would like to forward through your proxy:

web: bin/nscriptio [your existing command]

TCP Tunnel Mode

in this mode, your connection to localhost:[listen port] will be forwarded to [target host]:[target port] via your assigned IPs Modify your Procfile to prepend bin/nscriptio to any command whose connections you would like to forward through your proxy:

web: bin/nscriptio [your existing command]

set target host and port to connect to:

heroku config:set NSC_DST_HOST=[target host]
heroku config:set NSC_DST_PORT=[target port]

Now all you have to do is let your application connect to localhost:2356 port, traffic will be forwarded to your target server.

Here is an sample Node.js code for database connection

var mysql = require('mysql');

var con = mysql.createConnection({
  host: "localhost",
  port: "2356",
  user: "root",
  password: "mysuperduperpass"
});

con.connect(function(err) {
  if (err) throw err;
  console.log("Connected!");
  con.query("show databases", function (err, result) {
    if (err) throw err;
    console.log('result:----')
    console.log(result);
  })
});

Use with Node.js

You can use most http libraries with HTTP proxy, but not all of them work with HTTPS. Here we give an example on how to get Axios to work via HTTPS proxy:

const axios = require('axios');
const proxyagent = require('https-proxy-agent');

const agent = new proxyagent.HttpsProxyAgent(process.env.NSCRIPTIOD_HTTPS);
axios.get('https://ipinfo.io/ip', {proxy:false,httpsAgent:agent}).then(function(res){
  console.log(res);
});

Use with Ruby

rest-client and faraday doesn’t support SSL proxy, so you can only use it with a HTTP proxy. With typhoeus, you can use both protocols. Here are the examples for those:

rest-client

require "rest-client"

RestClient.proxy = ENV["NSCRIPTIOD_HTTP"]
res = RestClient.get("https://ipinfo.io/ip")
remoteIp = res.body
puts "IP: #{remoteIp}"

faraday

require 'faraday'

conn = Faraday.new(:url => "https://ipinfo.io/ip", :proxy => ENV["NSCRIPTIOD_HTTP"])
res = conn.get
remoteIp = res.body
puts "IP: #{remoteIp}"

typhoeus

require 'typhoeus'

_, username, password, host, port = ENV["NSCRIPTIOD_HTTPS"].gsub(/(:|\/|@)/,' ').squeeze(' ').split
res = Typhoeus.get(
  'https://ipinfo.io/ip',
  proxy: "https://#{host}:#{port}",
  proxyuserpwd: "#{username}:#{password}"
)
remoteIp = res.body
puts "IP: #{remoteIp}"

Use with Java

Most third-party network libraries support HTTP/HTTPS proxy. Here we use the native Java support by setting the proxy globally:

import java.net.*;
import java.io.*;

public class Test {
    public static void main(String []args) throws IOException {
        URL pUrl = new URL(System.getenv("NSCRIPTIOD_HTTPS"));
        String info = pUrl.getUserInfo();
        int i = info.indexOf(':');
        String user = info.substring(0, i);
        String password = info.substring(i + 1);

        System.setProperty("http.proxyHost", pUrl.getHost());
        System.setProperty("http.proxyPort", Integer.toString(pUrl.getPort()));

        Authenticator.setDefault(new Authenticator() {
                protected PasswordAuthentication getPasswordAuthentication() {
                    return new PasswordAuthentication(user, password.toCharArray());
                }
            });

        URL url = new URL("https://ipinfo.io/ip");
        URLConnection conn = url.openConnection();
        BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));

        String remoteIp = rd.readLine();
        System.out.println("IP:"+remoteIp);
    }
}

Use with Python

import os, requests

r = requests.get('https://ipinfo.io/ip', proxies={
              "http"  : os.getenv('NSCRIPTIOD_HTTPS'),
              "https" : os.getenv('NSCRIPTIOD_HTTPS')
            })
remoteIp=r.text
print('IP: '+remoteIp)

You can also set the proxy globally by using system http_proxy ENV

os.environ['http_proxy'] = os.getenv('NSCRIPTIOD_HTTP')
os.environ['https_proxy'] = os.getenv('NSCRIPTIOD_HTTP')
r = requests.get('https://ipinfo.io/ip')
remoteIp=r.text
print('IP: '+remoteIp)

Use with Golang

package main

import (
  "net/url"
  "net/http"
  "os"
  "io/ioutil"
)
func main () {
  proxyUrl, _ := url.Parse(os.Getenv("NSCRIPTIOD_HTTPS"))
  customClient := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxyUrl)}}
  resp, err = customClient.Get("https://ipinfo.io/ip")
  if (err != nil) {
    println(err.Error())
    return
  }
  defer resp.Body.Close()
  remoteIp, _ := ioutil.ReadAll(resp.Body)
  println("IP: "+string(remoteIp))
}

Use with PHP

<?php
  $ch = curl_init("https://ipinfo.io/ip");

  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_PROXY, getenv("NSCRIPTIOD_HTTPS"));

  $remoteIp = curl_exec($ch);
  print("IP: ".$remoteIp);
  curl_close($ch);
?>

Use with databases

Proxy wrapper tested to work with any TCP connection, including databases, please follow Global Proxy Wrapper usage

Migrating between Plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade nscriptiod:g50
-----> Upgrading nscriptiod:g50 to sharp-mountain-4005... done, v18 ($10/mo)
       Your plan has been updated to: nscriptiod:g50

Removing the add-on

Remove the add-on via the CLI.

heroku addons:destroy nscriptiod
-----> Removing nscriptiod from sharp-mountain-4005... done, v20 (free)

Support

Submit all NScriptio support tickets via one of the Heroku Support channels.

FAQ

Where can I see my usage data?

On the add-on’s dashboard.

How do the two IPs work?

Your traffic routes to your primary IP, the first one listed. If a request gets refused by target server or proxy server, the backup IP is used.