Tunneling

If you are developing on your local computer with one of the following integrations:

  • Office Scripts

  • Google Apps Script

you will need to expose your development server via a tunneling solution. This is because Office Scripts and Google Apps Script can only connect to servers on the Internet, but not directly to your local computer.

Tunneling isn’t necessary if you use an online development environment such as GitHub Codespaces.

Note

It’s important to trust the tunneling provider, as you are granting them access to route traffic to and from your local machine. Always ensure you are using a reputable provider to maintain the security of your development environment and check with your IT security department for allowed providers.

ngrok

ngrok is a popular provider and free for what we’ll use it for. Start by following their official docs:

  1. Create an account

  2. Install ngrok

Now you can run the following command on your Terminal/Command Prompt:

ngrok http 8000

You should see something along the following lines:

ngrok                                                                                                                (Ctrl+C to quit)

Share what you're building with ngrok https://ngrok.com/share-your-ngrok-story

Session Status                online
Account                       xxx@xxx.com (Plan: Free)
Version                       3.16.0
Region                        Europe (eu)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx.ngrok-free.app -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                            0       0       0.00    0.00    0.00    0.00

https://xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx.ngrok-free.app is the URL that you need to use as base URL in your runPython function in Office Scripts and Google Apps Script. This means that the complete URL to call a custom script would be (make sure to replace hello_world with the name of your custom script):

https://xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx.ngrok-free.app/xlwings/custom-scripts-call/hello_world

To exit ngrok again, hit Ctrl-C in your Terminal/Command Prompt.

Note

  • If you have certificates in your certs folder (see Development TLS Certs), you will need to run ngrok as follows so it connects to your local server running on https:

    ngrok http https://127.0.0.1:8000

  • You can configure ngrok so that it will always use the same URL, see the docs.

  • Note that by default, ngrok will expose your local web server publicly so anyone with the URL can access your backend.

Alternatives

Instead of ngrok, you can use many other solutions such as Cloudflare Tunnel. For a curated list of alternatives, see Awesome Tunneling.