Make the tunnel more stable with this one simple hack ✨

The Forge tunnel uses ngrok to connect the Forge backend to your local development server. However, ngrok only allows sessions of up to two hours and rate-limits traffic for anonymous users. When you reach one of these limits, you often have to restart the tunnel. :weary:

It turns out that you can remove the session limit and increase the rate limits by signing up for a free ngrok account (or using a paid account) and modifying a file in the tunnel package.

Note about Docker❗

The instructions below only work if you are using the tunnel without Docker. The hack should also work for the dockerized tunnel, but you would have to create a custom image based on atlassian/forge-tunnel and force the CLI to use the custom image instead of the latest version from the Docker Hub registry.

If you are using macOS or Linux, run which forge to find the install location of the CLI. For the output <path>/bin/forge, the file you need to modify is <path>/lib/node_modules/@forge/sandbox-tunnel/node_modules/@forge/tunnel/config/ngrok.yml. Add the line authtoken: <token>, replacing <token> with your ngrok Authtoken.

You can verify that the hack is working by opening http://localhost:4040 when the tunnel is running. There should be no warning message about the session limit and your Authtoken should be shown on the status page.


oddly, I get this far:
and don’t find the sandbox-tunnel directory

Running on
$ forge --version

I see now my cli is fairly out of date… will update and try again.

@jeffryan Have you installed the @forge/sandbox-tunnel package, as described here: Quick tip: Tunneling without Docker (useful for Apple Silicon / M1)?

1 Like

no actually - I wasn’t aware of that. We’ve just been running in docker and it’s been pretty bad. Does that package work on a intel mac?

The package should be platform independent. :+1:

I saw the comments in the package regarding cui invocations still requiring docker. Can we use that and still get a more reliable tunnel via the ngrok token?

I’m not in the Client-side UI kit EAP, but I’ll try to make it work once I have access.

Sorry, I was referring to Custom UI calling into the server using invoke calls. We aren’t using Client-side UI kit yet either.

Custom UI and resolvers are working perfectly. :+1:

1 Like

Anyone struggling with the @forge/cli update to 6.10.0 and the local tunnel.

This “hack” also solves problems described here: Error ERR_NGROK_120 (ngrok version not supported) when attempting to run tunnel

Thanks Christian!


It looks like the “Hack” doesn’t work anymore. I have added my ngrok auth token, but this message appears:

Tunnel uses an anonymous ngrok account, which has a time limit of 2 hours. After that time, you'll need to restart your tunnel.

Forge team should switch to Cloudflare Tunnel. Free, faster than ngrok and no time limit.

1 Like

I believe this is a hard coded warning and the CLI doesn’t actually check whether an Authtoken is used or not.

When you open http://localhost:4040 while the tunnel is running, is your Authtoken prefix shown on the “Status” page in the “Global” section? If it is, it should be working despite the warning.

Edit: If you want to get rid of the warning, open the file <path>/lib/node_modules/@forge/sandbox-tunnel/node_modules/@forge/tunnel/out/command/start-tunnel-command.js (see the original post to find out <path>) and remove the following line:

1 Like

We loved this hack so much we’ve added first class support into the Forge CLI for developers to supply a custom ngrok config when tunnelling.

Details are available on the Forge changelog


Hi Joe,
The new option “ngrok-config”, does’t work if you provide a full path to the ngrok config file. See:

macbook@MacBook-Pro-5 scheduler-forge % npm list -g                                                                               
├── @forge/cli@6.18.0
├── @forge/sandbox-tunnel@3.2.0
├── corepack@0.18.0
└── npm@9.6.7

macbook@MacBook-Pro-5 scheduler-forge % ngrok config check                                                                        
Valid configuration file at /Users/macbook/Library/ApplicationSupport/ngrok/ngrok.yml
macbook@MacBook-Pro-5 scheduler-forge % forge tunnel --ngrok-config  /Users/macbook/Library/ApplicationSupport/ngrok/ngrok.yml --verbose
ERROR:  Error reading configuration file '/Users/macbook/Library/ApplicationSupport/ngrok/ngrok.yml': read /Users/macbook/Library/ApplicationSupport/ngrok/ngrok.yml: is a directory

Workaround: copy the ngrok.yml into your project and run “”–ngrok-config ngrok.yml" .
We can confirm that forge tunnel with ngrok premium account works so much better:)



Glad to hear that the tunnel experience is improved for you :slight_smile:

I’ll follow up with the team on your bug report!

Fix for this bug is in the pipe and will be included in the next CLI release :+1:

1 Like

Is there any project or support especially for the tunnel? I have two other problems with it

Hi @ppasler

I’m not sure about your first concern regarding console.log messages not appearing in the tunnel - just confirming it is definitely server-side log messages and not browser (custom UI) log messages not appearing? If you can provide any additional information like a reproducible example, or --verbose log output, I would like to get the team to investigate further.

FORGE_DEV_TUNNEL is an internal setting for developing the CLI and not something we support officially. In @klaussner 's other post he specifically mentions that setting this variable can cause problems with function snapshotting on Node 16 and Node 18 - the workaround is to disable snapshotting while tunnelling - Quick tip: Tunneling without Docker (useful for Apple Silicon / M1)

The Native Node.js runtime will remove the docker dependency from the Forge CLI tunnel environment, and will eliminate snapshotting, so I anticipate that it will resolve many of the problems described here! Native Node.js runtime on Forge