Skip to content
This repository has been archived by the owner on Mar 29, 2021. It is now read-only.


Repository files navigation


Follow @MikeRogers on Twitter Gem Version Tests Passing RuboCop Standards

A plugin for puma that'll start a ngrok tunnel to your rails server when puma starts. Primary I built this to make the following a easier:

Deprecation Notice

This gem is not longer actively maintained, I suggest using theses alternatives instead:

What it does


  • Working with apps that require Webhooks to be received by the app to work correctly
  • Demoing your local rails app to someone else
  • Working with Puma-dev so your apps feels as production-like as possible
  • Testing on mobile.

I've setup a sample Rails 6 app which demos an implementation of this gem.


Adding ngrok package to your machine

Make sure you have installed ngrok on your machine:

$ brew tap caskroom/cask
$ brew cask install ngrok

Adding the gem

I've automated these steps into an app:template which can be found on Rails Bytes. However, if you'd like to install it manually follow these steps:

  1. Add this line to your application's Gemfile:
group :development do
  gem 'puma-ngrok-tunnel'
  1. And then execute:
$ bundle
  1. Append this line to your config/puma.rb file:
plugin :ngrok_tunnel if ENV.fetch('RAILS_ENV') { 'development' } == 'development'
  1. Lastly, update your config/environments/development.rb to include the line:
# puma-ngrok-tunnel: Allow connections from ngrok
config.hosts << /[a-z0-9.]


Read about how to configure puma to use this in the Puma documentation.

There are a few variables this plugin reads from the environment which control its behavior. These are based on the arguments you'd pass to the ngrok terminal command.

  • PORT - Optional, your rails port, defaults to 3000. If NGROK_ADDR is set, this is ignored.
  • NGROK_ADDR - Optional, if you're using Puma-dev set this to be your hostname & port, e.g. my-app-name.test:443.
  • NGROK_AUTHTOKEN - Optional, your ngrok authtoken. If you have ngrok configured on your local machine you don't need this.
  • NGROK_HOST_HEADER - Optional, if you're using Puma-dev you should set this to your virtual host e.g. my-app-name.test.
  • NGROK_CONFIG - Optional, your ngrok configuration file location, defaults to ~/.ngrok2/ngrok.yml.
  • NGROK_SUBDOMAIN - Optional, ngrok will assign you a random subdomain unless this is set.
  • NGROK_REGION - Optional, the region of your ngrok tunnel. The default is us.
  • NGROK_HOSTNAME - Optional, full ngrok hostname, shouldn't be set if NGROK_SUBDOMAIN is set.

Sample .env for use with rails s

# puma-ngrok-tunnel setup
# You need setup to make sure Puma can use these.
export NGROK_SUBDOMAIN=my-app-name
export NGROK_REGION=eu

Sample .env for use with Puma-dev

# Puma-dev: You need to define this otherwise it uses it's own puma.rb file.

# puma-ngrok-tunnel setup
# These should start with 'export' otherwise puma-dev won't use them.
export NGROK_SUBDOMAIN=my-app-name
export NGROK_REGION=eu
# The URL (and HTTPS Port) you might use to access this under Puma-dev
export NGROK_ADDR=my-app-name.test:443
export NGROK_HOST_HEADER=my-app-name.test

Pitfalls & solutions

The ngrok tunnel not always stopping when puma-dev stops

If you see an error saying http: proxy error: dial unix, it means ngrok was able to stop when puma was stopped. Right now the solution is to run:

pkill ngrok

in your terminal.

Rails 6 "Blocked host" error

If you seeing an error like:

Blocked host:

To allow requests to, add the following to your environment configuration:

config.hosts << ""

Open your config/environments/development.rb file add add:

# Safelist ngrok connections to development environment.
config.hosts << /[a-z0-9]+\.ngrok\.io/
# Safelist Puma-Dev hostname.
config.hosts << 'samplerailsapp.test'
config.hosts << /[a-z0-9]+\.samplerailsapp.test/

This will safe-list the ngrok subdomain to access your rails host.


The gem is available as open source under the terms of the MIT License.