> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Remote Tunnels

> Expose a local development server at a public HTTPS URL with VS Code port forwarding, ngrok, or GitHub Codespaces so BigCommerce can reach it.

A remote tunnel gives a server running on your machine a public HTTPS URL. Use one whenever the environment you're running locally needs to be reachable by outside systems.

There are several use cases for BigCommerce development:

* [Single-click app](/developer/docs/integrations/apps/guide/types-of-apps) callbacks and the control panel iframe that renders your app
* [Webhook](/developer/docs/integrations/webhooks) destination URLs
* An [Embedded Checkout](/developer/docs/admin/checkout-and-cart/embedded-checkout) channel site URL
* An HTTPS live preview of a [Stencil theme](/developer/docs/storefront/stencil/cli/development-server)

BigCommerce servers can't reach `http://localhost`, and the control panel only embeds HTTPS content. A tunnel forwards requests from a public HTTPS URL to a port on your machine.

This page covers three options. Pick the one that fits your environment.

| Option                                              | Best for                                                 | Requirements                                             | URL across restarts                                    |
| :-------------------------------------------------- | :------------------------------------------------------- | :------------------------------------------------------- | :----------------------------------------------------- |
| [VS Code port forwarding](#vs-code-port-forwarding) | Local development in VS Code or Cursor                   | VS Code or Cursor, a GitHub account                      | Usually stays the same                                 |
| [ngrok](#ngrok)                                     | Any editor or terminal, and inspecting incoming requests | The ngrok agent and a free ngrok account                 | Stays the same with your account's assigned dev domain |
| [GitHub Codespaces](#github-codespaces)             | A cloud dev environment with no local Node.js install    | A GitHub account and your project in a GitHub repository | Stays the same for the life of the codespace           |

> **Warning**
>
> A public tunnel makes your local server reachable by anyone who has the URL. Don't expose services that hold sensitive data, and stop the tunnel when you're done.

## VS Code port forwarding

VS Code includes port forwarding through Microsoft dev tunnels, so no extra software is needed. Cursor provides the same **Ports** view. For full details, see [Port forwarding (VS Code docs)](https://code.visualstudio.com/docs/debugtest/port-forwarding).

#### Start your local server

Start your dev server and note the port it listens on, for example `3000`.

#### Forward the port

Open the **Ports** view, using the **Ports** tab next to the terminal or the **Ports: Focus on Ports View** command, then click **Forward a Port**. If you haven't connected VS Code to GitHub before, sign in when prompted. Then enter the port number.

![VS Code Ports view with the Forward a Port button](/_fern-img/7b3a458f1b94e3f5db92293040b218eaf53d0bb38e3c33ec007a1d18f37b54d4.webp)

#### Make the port public

Right-click the forwarded port and select **Port Visibility** > **Public**.

![VS Code Ports view context menu showing Port Visibility set to Public](/_fern-img/324ded5e824293604f015a541d3871a6ada1449e90d93c661a522628d6ef076f.webp)

> **Warning**
>
> You must make the port public. Forwarded ports are private by default, and a private port requires a GitHub sign-in, so BigCommerce servers get a login page instead of your app.

#### Copy the forwarded address

Copy the `https://<SUBDOMAIN>.devtunnels.ms` URL from the **Forwarded Address** column. Click the globe icon next to the port to open it in a browser.

## ngrok

[ngrok](https://ngrok.com/) is a dedicated tunneling tool. It works from any terminal, and its traffic inspector shows every external request, which helps when debugging webhooks and app callbacks. For full details, see the [ngrok agent documentation](https://ngrok.com/docs/agent/).

#### Install ngrok

Download the agent for your operating system from the [ngrok downloads page](https://ngrok.com/downloads). To use a package manager instead, run `brew install ngrok/ngrok/ngrok` on macOS or `choco install ngrok` on Windows.

#### Connect your account

[Sign up for a free ngrok account](https://dashboard.ngrok.com/signup), copy your [authtoken](https://dashboard.ngrok.com/get-started/your-authtoken), and add it to your ngrok configuration. Unauthenticated tunnels expire quickly.

```bash showLineNumbers={false}
ngrok config add-authtoken <YOUR_AUTHTOKEN>
```

#### Start your local server

Start your dev server and note the port it listens on, for example `3000`.

#### Start the tunnel

In a second terminal, start a tunnel to that port.

```bash showLineNumbers={false}
ngrok http 3000
```

#### Copy the forwarding URL

Copy the `https://<SUBDOMAIN>.ngrok-free.app` URL from the **Forwarding** line of the ngrok output. Keep ngrok running while you work.

To inspect requests and responses, open the ngrok traffic inspector at `http://localhost:4040`.

Free ngrok accounts include one assigned dev domain, so the forwarding URL stays the same each time you start the tunnel. Free accounts also show an interstitial warning page in front of browser traffic. If it appears, click **Visit** to continue. For other ways to remove it, see [Free plan limits (ngrok docs)](https://ngrok.com/docs/pricing-limits/free-plan-limits).

## GitHub Codespaces

GitHub Codespaces runs your project in a cloud dev container and forwards its ports. This configuration replicates the same experience as [VS Code port forwarding](#vs-code-port-forwarding), just in a remote environment. For full details, see [Forwarding ports in your codespace (GitHub docs)](https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace).

#### Create a codespace

Push your project to a GitHub repository you own, or fork a starter repository. On the repository page, click **Code** > **Codespaces** > **Create codespace on main**.

#### Set up and start the project

In the codespace terminal, complete your project's setup, such as installing dependencies and creating environment files, then start the dev server. Codespaces detects the port and forwards it automatically.

#### Make the port public

In the **Ports** view, right-click the forwarded port and select **Port Visibility** > **Public**. Ports are private by default, which blocks requests from BigCommerce.

#### Copy the forwarded address

Copy the `https://<CODESPACE_NAME>-<PORT>.app.github.dev` URL from the **Forwarded Address** column.

Codespaces stop when idle. The forwarded URL usually stays the same when you restart a codespace, but its visibility can reset to private. If BigCommerce requests start failing after a restart, check the port visibility again.

## Verify the tunnel

Before you use the URL in any BigCommerce configuration, open it in a browser, or in a private window if you used port forwarding, to confirm it loads your local server. If it shows a login page, an error, or nothing at all, see [Troubleshooting](#troubleshooting).

## Update your configuration when the URL changes

BigCommerce stores the tunnel URL wherever you enter it, so it doesn't update on its own. Whenever your tunnel URL changes, update every place that references it, for example:

* **Apps:** your app's origin environment variable, such as `APP_ORIGIN`, and all callback URLs in the [Developer Portal](https://build.bigcommerce.com/). Restart the dev server afterward. If the app is already installed, uninstall and reinstall it.
* **Webhooks:** the `destination` of each webhook that points to the old URL.
* **Embedded Checkout:** the channel site URL.

Keeping a single tunnel running for your whole work session, or using an option with a stable URL, saves you from repeating these updates.

## Troubleshooting

**Requests get a login page instead of your server.** The forwarded port is private. Set its visibility to **Public** in the **Ports** view.

**Nothing reaches your server.** The tunnel or the dev server isn't running, the tunnel points to the wrong port, or the URL has changed. Confirm both processes are running, then open the tunnel URL in a browser.

**BigCommerce still calls an old URL.** Update every reference to the tunnel URL, as described in [Update your configuration when the URL changes](#update-your-configuration-when-the-url-changes).

**`ngrok` command not found.** ngrok isn't on your system `PATH`. Either move the binary into a directory on your `PATH` (for example, `mv ngrok /usr/local/bin` on macOS and Linux, or add the folder containing `ngrok.exe` to your `PATH` environment variable on Windows), or run it from its folder with `./ngrok http 3000` on macOS and Linux or `.\ngrok.exe http 3000` in Windows PowerShell.

## Related resources

* [Apps quick start](/developer/docs/integrations/apps/quick-start)
* [Tutorial: Single-click app](/developer/docs/integrations/apps/tutorial-single-click-app)
* [Webhooks tutorial](/developer/docs/integrations/webhooks/tutorial)
* [Stencil CLI live preview](/developer/docs/storefront/stencil/cli/development-server)