· engineering

Run a Frontend and API Together From One Tunnel File

Stop juggling multiple terminals. Learn how to configure instawormhole.toml to launch up to 10 local frontend and backend tunnels simultaneously from one CLI command.

By InstaWormhole team, Engineering

Run a Frontend and API Together From One Tunnel File

Full-stack development rarely happens on a single port. Even a straightforward web application typically requires a frontend development server running on one local port—such as 127.0.0.1:3000 for React, Next.js, or Vite—and a backend API server running on another, such as 127.0.0.1:8080 for Node.js, Go, Python, or Rust. When you need to expose both local services over public HTTPS addresses simultaneously to test webhooks, preview mobile layouts, share work in progress with teammates, or verify cross-origin authentication flows, managing separate tunnel commands across multiple terminal tabs quickly becomes tedious.

InstaWormhole addresses this workflow bottleneck with declarative configuration via instawormhole.toml. Instead of running separate commands for every port on your machine, you can define up to 10 tunnels inside a single file and start every tunnel in the file from one connector process using npx @instawormhole/connector run --config instawormhole.toml --stored-device (with Node.js 20 or later).

This guide walks through configuring instawormhole.toml to expose a local frontend and backend API side by side, connecting to durable tunnels from the dashboard, and avoiding the strict formatting and validation checks that trigger config_invalid.

Why Use a Single Configuration File for Full-Stack Tunnels?

Running separate tunnel commands in multiple terminal windows introduces operational friction during active development:

  • Fragmented terminal management: Keeping track of which terminal tab corresponds to your UI versus your API slows down debugging when you need to restart local servers or inspect connection output.
  • Inconsistent lifecycle state: If one tunnel process is stopped or closed accidentally while another remains running, your frontend may attempt to reach an inactive public API endpoint.
  • Repetitive command-line flags: Passing relay URLs, loopback origins, device credentials, and tunnel identifiers repeatedly via CLI arguments becomes error-prone as soon as you expose more than one service.

By centralizing your tunnel definitions in instawormhole.toml, your local routing topology lives alongside your project or configuration directory. According to the InstaWormhole documentation on running several tunnels from one file, a single command reads the file, starts every tunnel defined in it, and prints each public address while opening outbound connections through the relay.

"Start several tunnels, for example a web app and an API, with one command." — InstaWormhole Docs: Run several tunnels from one file

Anatomy of instawormhole.toml

An instawormhole.toml configuration file consists of a top-level relay endpoint declaration followed by one or more [[tunnel]] sections (up to 10 tunnels per file). Each [[tunnel]] section maps a local loopback origin to a public tunnel address.

Below is the standard configuration pattern for pairing a frontend application on port 3000 with an API server on port 8080:

relay = "wss://relay.instawormhole.site"

[[tunnel]]
name = "web"
origin = "127.0.0.1:3000"

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"

Top-Level Configuration Keys

At the root of instawormhole.toml, you specify the relay endpoint that the connector uses:

  • relay: Specifies the InstaWormhole relay endpoint using plain double-quoted strings, set to "wss://relay.instawormhole.site".

Tunnel Entry Keys ([[tunnel]])

Each [[tunnel]] section defines an individual tunnel started by the connector process, with a maximum of 10 tunnels in one file:

  • name: A label for the tunnel entry (for example, "web" or "api").
  • origin: The local loopback address and port where your service is listening (for example, "127.0.0.1:3000" or "127.0.0.1:8080").
  • tunnel (optional): The ID of a durable tunnel from the InstaWormhole dashboard. Including this key connects that entry to an existing durable tunnel rather than opening a temporary address.
KeyLevelRequiredDescriptionExample
relayRootYesInstaWormhole relay endpoint string"wss://relay.instawormhole.site"
name[[tunnel]]YesLabel for the tunnel entry"web"
origin[[tunnel]]YesLocal loopback address and port"127.0.0.1:3000"
tunnel[[tunnel]]NoDurable tunnel ID from the dashboard"0199aa00-0000-7000-8000-00000000000c"

Step-by-Step: Running Your Frontend and API Together

Follow these steps to set up and run both your frontend and backend services through a single instawormhole.toml file.

1. Start Your Local Frontend and Backend Servers

Before running the connector, start both local applications and confirm they are listening on loopback addresses:

  1. Start your frontend server on a loopback address such as 127.0.0.1:3000 or localhost:3000.
  2. Start your backend API server on a loopback address such as 127.0.0.1:8080.

Checking both local endpoints first ensures that once the connector prints each public HTTPS address, incoming traffic reaches active local servers rather than refused connections. Note also that framework dev servers such as Vite and Next.js may require configuration to accept your tunnel's address when accessed over HTTPS with hot reload.

2. Create Your instawormhole.toml File

Create a file named instawormhole.toml in the folder where you will run the connector:

relay = "wss://relay.instawormhole.site"

[[tunnel]]
name = "web"
origin = "127.0.0.1:3000"

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"

If you work in a shared repository and include durable tunnel IDs or personal configuration details in instawormhole.toml, add instawormhole.toml to .gitignore or keep a sanitized example file in version control.

3. Sign In Your Computer (--stored-device)

As documented in Expose localhost:3000 with npx: Run Options and Run several tunnels from one file, --config requires --stored-device so the connector uses the sign-in saved for your device. Follow the device sign-in steps in the InstaWormhole documentation if this computer has not yet been signed in. On Linux, --store file can also be added to commands to keep credentials in a private file instead of the operating system store.

4. Launch All Tunnels With One Command

Run the connector from the directory containing your configuration file:

npx @instawormhole/connector run --config instawormhole.toml --stored-device

The connector starts every tunnel defined in instawormhole.toml and prints each public address. HTTP, WebSockets, and streaming responses pass through the connector, allowing modern frontend dev servers and live connections to work over the assigned HTTPS addresses.

5. Point Your Frontend to the Public API Tunnel URL

Once the connector prints the public addresses for your web and api tunnels, update your frontend environment variables (such as NEXT_PUBLIC_API_URL or VITE_API_BASE_URL) so browser requests from the public frontend address target the public api tunnel address rather than a local-only port unreachable from external devices or third-party services.

When testing on a phone, sharing work in progress, or receiving webhooks from external providers, both your frontend UI and backend API remain reachable through their respective public HTTPS URLs for as long as the connector runs.

Connecting Durable Tunnels From the Dashboard

When you omit the tunnel key in a [[tunnel]] block, the connector opens a temporary address for that entry. Temporary addresses are convenient for quick experiments, whereas durable tunnels from the dashboard provide distinct advantages documented in Expose localhost:3000 with npx: Run Options and InstaWormhole:

  • Stable addresses: A durable tunnel keeps its address across sessions and automatic reconnections.
  • Access protection: Durable tunnels can be protected with access controls such as passwords, access tokens, email codes, or IP lists.
  • Request inspection: Durable tunnels show their requests in the request inspector.

To connect a [[tunnel]] entry in instawormhole.toml to a durable tunnel:

  1. Locate or create the durable tunnel in the InstaWormhole dashboard and copy its tunnel ID.
  2. Add the optional tunnel key with that ID to the matching [[tunnel]] block in instawormhole.toml.
relay = "wss://relay.instawormhole.site"

[[tunnel]]
name = "web"
origin = "127.0.0.1:3000"
tunnel = "0199aa00-0000-7000-8000-000000000001"

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"
tunnel = "0199aa00-0000-7000-8000-000000000002"

When you run npx @instawormhole/connector run --config instawormhole.toml --stored-device, each entry connects to its specified durable tunnel while forwarding traffic to its local loopback origin. Keep in mind account and plan allowances as well: for example, the Free plan supports 3 tunnels online at once, 5 GB transfer a month, 120 requests a minute per tunnel, sessions up to 24 hours, and 1 reserved address, while paid plans start at $4.99 a month.

Scaling Up: Running Up to 10 Services Together

A single instawormhole.toml file supports up to 10 tunnels from one connector process, making it practical to expose multiple local services—such as a web app, an admin interface, a core API, and background or worker endpoints—from one command:

relay = "wss://relay.instawormhole.site"

[[tunnel]]
name = "web"
origin = "127.0.0.1:3000"

[[tunnel]]
name = "admin"
origin = "127.0.0.1:3001"

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"

[[tunnel]]
name = "auth-service"
origin = "127.0.0.1:8081"

[[tunnel]]
name = "webhook-worker"
origin = "127.0.0.1:9000"

Pressing Ctrl+C stops the connector so the public addresses stop answering. If the connection drops—for example, when your computer sleeps—the connector reconnects on its own, and durable tunnels keep their addresses.

Validation Rules and config_invalid Watch-Outs

According to Run several tunnels from one file, if something is wrong with the configuration file, the connector stops with the error config_invalid. The file format is intentionally strict to protect you from a typo that could expose something unexpected.

1. Loopback-Only Origins

Every origin in instawormhole.toml must be a loopback address (such as 127.0.0.1:3000, localhost:5173, or [::1]:3000). A configuration file or --origin value that specifies a non-loopback address is refused.

  • Valid origin: origin = "127.0.0.1:3000"
  • Invalid origin: origin = "192.168.1.50:3000" (non-loopback address is refused)
  • Invalid origin: origin = "example.com:80" (non-loopback host is refused)

2. Up to 10 Tunnels Per File

A single configuration file supports up to 10 tunnels. Defining more than 10 tunnels in one file triggers config_invalid. If you need to manage additional tunnels across separate sets of services, split them into multiple configuration files and run separate connector commands.

3. Strict Allowed Keys, Plain Double-Quoted Strings, and Comments

The documentation specifies that only the documented keys are allowed, using plain double-quoted strings and # comments. Unknown keys, malformed syntax, or invalid values cause the connector to stop with config_invalid, and the message names the key or value to fix. Also note from Expose localhost:3000 with npx: Run Options that the connector refuses an option given twice rather than letting the last occurrence win.

Configuration MistakeWhy It FailsHow to Fix It
Non-loopback origin addressEvery origin must be a loopback addressUse a loopback address such as 127.0.0.1:3000 or localhost:3000
More than 10 tunnels in one fileOne file opens up to 10 tunnelsKeep total tunnels in instawormhole.toml to 10 or fewer, or split into another file
Unallowed keys or syntax errorsFile format allows only documented keys, plain double-quoted strings, and # commentsFix the key or value named in the config_invalid message
Duplicate CLI optionsConnector refuses an option given twicePass each flag once per command invocation

Troubleshooting Checklist

When a multi-tunnel setup needs debugging, work through these checks using the InstaWormhole documentation:

  • Connector exits with config_invalid: Inspect the error message for the key or value named, confirm every origin is a loopback address, verify you have at most 10 tunnels in the file, and check that you only use allowed keys, plain double-quoted strings, and # comments.
  • App does not respond or times out: Verify your local frontend and API servers are running on their configured loopback ports, and check --origin-timeout options if your app needs longer response or idle windows (from 1 to 3600 seconds; defaults are 10 minutes to wait for a response to start and 2 minutes with no data).
  • Cross-origin requests between frontend and API tunnels: Because your frontend tunnel and API tunnel have separate public HTTPS addresses, ensure your API server allows requests from your public frontend tunnel origin and that your frontend framework is configured for tunnel usage.
  • Sign-in or diagnostic issues: Confirm the computer is signed in when using --stored-device, inspect traffic in the request inspector on durable tunnels, and use Tunnel Doctor or the diagnostic documentation in InstaWormhole Docs to check DNS, TLS, connector, protection, and app layers.

Summary of Commands and Configuration

Keep this minimal configuration and command handy when setting up a frontend and API together:

relay = "wss://relay.instawormhole.site"

[[tunnel]]
name = "web"
origin = "127.0.0.1:3000"

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"

Launch the configured tunnels with:

npx @instawormhole/connector run --config instawormhole.toml --stored-device

Using instawormhole.toml keeps your frontend and API tunnel definitions in one place, lets you start up to 10 tunnels from a single command, and supports both temporary and durable dashboard tunnels. For complete details on device sign-in, framework guides, access protection, and diagnostics, consult the InstaWormhole documentation.