<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[InstaWormhole]]></title><description><![CDATA[InstaWormhole]]></description><link>https://instawormhole.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sat, 21 Nov 2026 14:44:54 GMT</lastBuildDate><atom:link href="https://instawormhole.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Debug Broken Tunnels Fast With Tunnel Doctor]]></title><description><![CDATA[Debug localhost tunnel failures layer by layer with Tunnel Doctor across DNS, TLS, connector, access protection, and local app checks, and look up]]></description><link>https://instawormhole.hashnode.dev/debug-broken-tunnels-fast-with-tunnel-doctor</link><guid isPermaLink="true">https://instawormhole.hashnode.dev/debug-broken-tunnels-fast-with-tunnel-doctor</guid><category><![CDATA[networking]]></category><category><![CDATA[Devops]]></category><category><![CDATA[webdev]]></category><category><![CDATA[programming]]></category><category><![CDATA[api]]></category><dc:creator><![CDATA[InstaWormhole]]></dc:creator><pubDate>Sat, 21 Nov 2026 02:30:36 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6afd4935db431bf520bd4a87/892eb887-abf6-447f-a17e-d78ae0843756.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>When a public tunnel address stops reaching your local app, the symptom rarely tells you where the problem is. A blank page, a 502, a timeout and a password prompt you did not expect can each come from a different part of the path between the internet and your machine. Guessing means restarting servers and retrying requests while a demo or webhook test waits.</p>
<p>InstaWormhole’s <strong>Tunnel Doctor</strong> replaces the guessing. According to the <a href="https://instawormhole.com/docs/diagnose/tunnel-doctor">Tunnel Doctor guide</a>, it finds which part of the path from the internet to your app is failing and tells you what to do about it. This article explains how it works, how to read its results, and how to use its diagnostic codes.</p>
<h2>What Tunnel Doctor Does</h2>
<p>Tunnel Doctor applies to durable tunnels on all plans, and the docs estimate a run at about 3 minutes. You start it from the dashboard: open the tunnel and choose <strong>Run Tunnel Doctor</strong>. The button changes to “Checking every layer” and then shows the result.</p>
<p>A few things are worth knowing before you run it:</p>
<ul>
<li>It sends one GET request to the tunnel’s public address.</li>
<li>It sends no credentials and follows no redirects.</li>
<li>It keeps only the status and the relay’s code. It changes nothing, and a report is not stored.</li>
<li>The request is sent from the InstaWormhole edge, so the docs note that it is not an independent outside check.</li>
<li>You can run it once every 10 seconds for a tunnel.</li>
</ul>
<h2>The Seven Layers, in Request Order</h2>
<p>Tunnel Doctor checks the layers in the order a request travels:</p>
<ol>
<li>Address lookup (DNS)</li>
<li>Secure connection (TLS)</li>
<li>Tunnel state</li>
<li>Connector</li>
<li>Access protection</li>
<li>Your app</li>
<li>Request through the public address</li>
</ol>
<p>The order matters because an earlier failure can explain later ones. The docs say to start with the first layer marked as failing and follow its instruction. Fixing that layer often clears the layers after it.</p>
<blockquote>
<p>Fix the first failing layer, then run Tunnel Doctor again. The layer you fixed should show as passing.</p>
</blockquote>
<h2>Reading the Overall Result</h2>
<p>Tunnel Doctor gives one of four overall results:</p>
<table>
<thead>
<tr>
<th>Result</th>
<th>What it means</th>
</tr>
</thead>
<tbody><tr>
<td>Working: a request through the public address reached your app</td>
<td>Every layer passed.</td>
</tr>
<tr>
<td>Working, with something to look at</td>
<td>The tunnel works and one layer has a warning.</td>
</tr>
<tr>
<td>Not working</td>
<td>A layer failed. Fix the first failing layer.</td>
</tr>
<tr>
<td>Checked up to the password prompt</td>
<td>The tunnel has a password, so the check stopped at the prompt. This is expected.</td>
</tr>
</tbody></table>
<p>The last result is not a failure. If your tunnel has a password, the checker cannot see past the prompt. Open the address yourself and sign in to confirm your app answers.</p>
<h2>Diagnostic Codes Tell You Who Fixes It</h2>
<p>Each finding has a stable diagnostic code. The <a href="https://instawormhole.com/docs/diagnose/diagnostic-codes">diagnostic code reference</a> groups every code by layer and says who fixes it. <strong>You</strong> means the fix is on your computer or in your dashboard. <strong>InstaWormhole</strong> means the problem is on InstaWormhole’s side and there is nothing to change on yours.</p>
<p>That distinction saves time. Some findings you can resolve immediately, and others only need a re-check:</p>
<table>
<thead>
<tr>
<th>Layer</th>
<th>Example code</th>
<th>Who fixes it</th>
<th>What the docs say to do</th>
</tr>
</thead>
<tbody><tr>
<td>Address lookup (DNS)</td>
<td><code>DNS_NO_RECORD</code></td>
<td>InstaWormhole</td>
<td>Nothing to change on your side. Run the check again in a few minutes, and contact support with the diagnostic ID if it continues.</td>
</tr>
<tr>
<td>Secure connection (TLS)</td>
<td><code>TLS_HANDSHAKE_FAILED</code></td>
<td>InstaWormhole</td>
<td>Run the check again in a minute, and contact support if it continues.</td>
</tr>
<tr>
<td>Tunnel state</td>
<td><code>ROUTE_PAUSED</code></td>
<td>You</td>
<td>Resume the tunnel, then start the connector again with the command under Connect an app.</td>
</tr>
<tr>
<td>Connector</td>
<td><code>CONNECTOR_OFFLINE</code></td>
<td>You</td>
<td>Start the connector on the computer running your app, and check its output for an error if it is already running.</td>
</tr>
<tr>
<td>Connector</td>
<td><code>CONNECTOR_UNAVAILABLE</code></td>
<td>You</td>
<td>The connector is recorded as connected but did not take the request. Restart it with Ctrl+C, then the command under Connect an app.</td>
</tr>
<tr>
<td>Access protection</td>
<td><code>ACCESS_UNAVAILABLE</code></td>
<td>InstaWormhole</td>
<td>The edge could not apply the tunnel’s access rule, so it refuses visitors. Run the check again in a minute.</td>
</tr>
<tr>
<td>Your app</td>
<td><code>ORIGIN_UNREACHABLE</code></td>
<td>You</td>
<td>Make sure your app is running and that the <code>--origin</code> address in the connector command matches the port it listens on.</td>
</tr>
<tr>
<td>Request through the public address</td>
<td><code>REQUEST_PROTECTED</code></td>
<td>Nothing to fix</td>
<td>The checker does not know the password, so open the address yourself and sign in.</td>
</tr>
</tbody></table>
<p>When you contact support, quote the code and the diagnostic ID.</p>
<h2>Walking Through Common Failures</h2>
<h3>The Tunnel Was Paused or Stopped</h3>
<p>If Tunnel Doctor reports <code>ROUTE_PAUSED</code> or <code>ROUTE_STOPPED</code>, the fix is on your side. Resume the tunnel in the dashboard, then start the connector again with the command shown under Connect an app. An expired tunnel (<code>ROUTE_EXPIRED</code>) is different, because the docs say it cannot be switched on again. You need to create a new tunnel and connect your app to it.</p>
<h3>The Connector Is Offline or Not Taking Requests</h3>
<p><code>CONNECTOR_OFFLINE</code> means the connector is not running. Start it on the computer that runs your app. The docs show the durable tunnel form of the command like this, with the tunnel ID copied from the tunnel’s Connect an app section:</p>
<pre><code>npx @instawormhole/connector run --relay wss://relay.instawormhole.site --origin 127.0.0.1:3000 --stored-device --tunnel &lt;tunnel id&gt;
</code></pre>
<p><code>CONNECTOR_UNAVAILABLE</code> is the case where the connector is recorded as connected but did not take the request, and the fix is to restart it. The docs also say that if the connection drops, for example when your computer sleeps, the connector reconnects on its own and a durable tunnel keeps its address. If it does not recover, restart it.</p>
<h3>Your App Is Not Where the Connector Expects</h3>
<p><code>ORIGIN_UNREACHABLE</code> means the connector could not reach your app. Check that the app is running and that the port in <code>--origin</code> matches the port it listens on, for example <code>127.0.0.1:3000</code>. The connector only accepts loopback addresses for <code>--origin</code>, and the docs say a local server that only accepts HTTPS is not supported.</p>
<p>Two related codes cover slow or crashing apps:</p>
<ul>
<li><code>ORIGIN_SLOW</code>: your app accepted the request but did not answer within 15 seconds. Check whether it is busy or stuck, and that the start page answers quickly.</li>
<li><code>ORIGIN_NO_RESPONSE</code>: your app closed the connection without sending a response. Check your app’s logs for a crash or an error on <code>GET /</code>.</li>
</ul>
<p>Tunnel Doctor sends its check to your app with an <code>X-Instawormhole-Diagnostic</code> header, so your app’s logs show the request. This helps you confirm that the check actually arrived.</p>
<h3>A Development Server Refuses the Tunnel’s Address</h3>
<p>If a page loads unstyled or says “Blocked request”, your development server may be refusing the tunnel’s address. Tunnel Doctor recognises common cases and shows the exact line to add, with your address filled in. The docs list these codes:</p>
<ul>
<li><code>REQUEST_VITE_HOST_BLOCKED</code>: add the tunnel’s address to <code>server.allowedHosts</code> in <code>vite.config.js</code>, then restart the dev server.</li>
<li><code>REQUEST_VITE_PREVIEW_HOST_BLOCKED</code>: add it to <code>preview.allowedHosts</code>, then restart <code>vite preview</code>.</li>
<li><code>REQUEST_NEXT_DEV_ORIGIN_BLOCKED</code>: add it to <code>allowedDevOrigins</code> in <code>next.config.js</code>, then restart <code>next dev</code>.</li>
<li><code>REQUEST_VITE_HMR_UNREACHABLE</code>: point Vite’s live reload at the tunnel on port 443 over <code>wss</code>, then restart the dev server. In Vite 8 the same keys sit under <code>server.ws</code>.</li>
</ul>
<h3>The Tunnel Asks for a Password You Did Not Expect</h3>
<p>If the address prompts for a password, the tunnel has a password or token set. Open the address in a private window and sign in, or send the token header. Tunnel Doctor reports this as “Checked up to the password prompt”, and the <code>REQUEST_PROTECTED</code> code means the same thing. The docs separately describe <code>ACCESS_NOT_ENFORCED</code>, where a request without the password reached your app. In that case they tell you to pause the tunnel immediately and contact support with the diagnostic ID.</p>
<h3>Limits That Look Like Outages</h3>
<p>Some failures come from plan limits rather than faults. The docs describe two:</p>
<ul>
<li><code>ROUTE_TRANSFER_LIMIT</code>: the workspace has used its plan’s monthly transfer allowance (5 GB on Free). Tunnels serve again on the 1st of next month (UTC).</li>
<li><code>REQUEST_RATE_LIMITED</code>: the tunnel is getting more requests a minute than its plan allows (120 on Free), so the relay turned the check away. Run the check again in a minute, and if real visitors see this too, reduce automated traffic to the address.</li>
</ul>
<p>If the address answers 429, the troubleshooting guide says the same thing: wait a minute, or see the plan limits page.</p>
<h3>Custom Domains</h3>
<p>If you connect your own domain, Tunnel Doctor also reports custom domain codes. These use a status of pass, warning, unknown or fail:</p>
<ul>
<li><code>DOMAIN_ACTIVE</code>: the domain is active.</li>
<li><code>DOMAIN_WAITING</code>: nothing to do yet, so run the check again in a few minutes.</li>
<li><code>DOMAIN_RECORDS_MISSING</code>: create the missing record at your DNS provider, exactly as shown under Custom domain. The docs say DNS changes can take up to an hour to show.</li>
<li><code>DOMAIN_FAILED</code> and <code>DOMAIN_DETACHED_DNS</code>: fix or restore the records at your DNS provider, then choose Check again under Custom domain.</li>
</ul>
<h2>When the Symptom Is All You Have</h2>
<p>Sometimes you only see the browser symptom. The <a href="https://instawormhole.com/docs/diagnose/tunnel-not-working">troubleshooting guide</a> maps common symptoms to causes. It recommends running Tunnel Doctor first because it names the failing layer.</p>
<table>
<thead>
<tr>
<th>What you see</th>
<th>What the docs say it means</th>
</tr>
</thead>
<tbody><tr>
<td>404 with no page</td>
<td>No connector is serving this address. Resume the tunnel if it is paused or stopped, and start the connector.</td>
</tr>
<tr>
<td>502 or 503</td>
<td>The connector is connected but could not reach your app. Make sure the app is running and that <code>--origin</code> matches its port.</td>
</tr>
<tr>
<td>Timeout</td>
<td>Your app is slow to answer. By default the connector waits up to 10 minutes for a response to start and 2 minutes with no data. You can raise the wait with <code>--origin-timeout</code>.</td>
</tr>
<tr>
<td>429</td>
<td>The tunnel hit its plan’s requests-per-minute limit or the workspace hit its monthly transfer.</td>
</tr>
<tr>
<td>410, “disabled”</td>
<td>The tunnel’s address was disabled for violating the Acceptable Use Policy. Contact support with the tunnel address if you think this is a mistake.</td>
</tr>
</tbody></table>
<h2>A Repeatable Workflow</h2>
<ol>
<li>Open the tunnel in the dashboard and choose <strong>Run Tunnel Doctor</strong>.</li>
<li>Read the overall result.</li>
<li>Find the first layer marked as failing.</li>
<li>Look up its diagnostic code in the <a href="https://instawormhole.com/docs/diagnose/diagnostic-codes">diagnostic code reference</a> to see who fixes it and what to try.</li>
<li>Apply the fix.</li>
<li>Run Tunnel Doctor again and confirm the layer now passes.</li>
</ol>
<p>The docs define the finish line clearly. You are done when the overall result says Working, or when it names the first layer that failed and what to do.</p>
<h2>Conclusion</h2>
<p>A broken tunnel is much easier to fix once you know which layer failed. Tunnel Doctor checks the seven layers in request order, gives each finding a stable code, and tells you whether the fix is yours or InstaWormhole’s. Run it first, fix the first failing layer, and run it again. For anything it cannot resolve, contact support with the code and the diagnostic ID. The full details are in the <a href="https://instawormhole.com/docs">InstaWormhole documentation</a>.</p>
<hr />
<p><em>Originally published at <a href="https://instawormhole.com/blog/debug-broken-tunnels-fast-with-tunnel-doctor">https://instawormhole.com/blog/debug-broken-tunnels-fast-with-tunnel-doctor</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Run a Frontend and API Together From One Tunnel File]]></title><description><![CDATA[Stop juggling multiple terminals. Learn how to configure instawormhole.toml to launch up to 10 local frontend and backend tunnels simultaneously]]></description><link>https://instawormhole.hashnode.dev/run-a-frontend-and-api-together-from-one-tunnel-file</link><guid isPermaLink="true">https://instawormhole.hashnode.dev/run-a-frontend-and-api-together-from-one-tunnel-file</guid><category><![CDATA[networking]]></category><category><![CDATA[Devops]]></category><category><![CDATA[webdev]]></category><category><![CDATA[programming]]></category><category><![CDATA[Security]]></category><dc:creator><![CDATA[InstaWormhole]]></dc:creator><pubDate>Fri, 20 Nov 2026 02:19:51 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6afd4935db431bf520bd4a87/82f3497b-caea-4574-a561-efc9950194a2.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>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 <code>127.0.0.1:3000</code> for React, Next.js, or Vite—and a backend API server running on another, such as <code>127.0.0.1:8080</code> 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.</p>
<p>InstaWormhole addresses this workflow bottleneck with declarative configuration via <code>instawormhole.toml</code>. 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 <code>npx @instawormhole/connector run --config instawormhole.toml --stored-device</code> (with Node.js 20 or later).</p>
<p>This guide walks through configuring <code>instawormhole.toml</code> 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 <code>config_invalid</code>.</p>
<h2>Why Use a Single Configuration File for Full-Stack Tunnels?</h2>
<p>Running separate tunnel commands in multiple terminal windows introduces operational friction during active development:</p>
<ul>
<li><strong>Fragmented terminal management:</strong> 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.</li>
<li><strong>Inconsistent lifecycle state:</strong> If one tunnel process is stopped or closed accidentally while another remains running, your frontend may attempt to reach an inactive public API endpoint.</li>
<li><strong>Repetitive command-line flags:</strong> 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.</li>
</ul>
<p>By centralizing your tunnel definitions in <code>instawormhole.toml</code>, your local routing topology lives alongside your project or configuration directory. According to the <a href="https://instawormhole.com/docs/connect/several-tunnels">InstaWormhole documentation on running several tunnels from one file</a>, a single command reads the file, starts every tunnel defined in it, and prints each public address while opening outbound connections through the relay.</p>
<blockquote>
<p>"Start several tunnels, for example a web app and an API, with one command." — <a href="https://instawormhole.com/docs/connect/several-tunnels">InstaWormhole Docs: Run several tunnels from one file</a></p>
</blockquote>
<h2>Anatomy of <code>instawormhole.toml</code></h2>
<p>An <code>instawormhole.toml</code> configuration file consists of a top-level <code>relay</code> endpoint declaration followed by one or more <code>[[tunnel]]</code> sections (up to 10 tunnels per file). Each <code>[[tunnel]]</code> section maps a local loopback origin to a public tunnel address.</p>
<p>Below is the standard configuration pattern for pairing a frontend application on port <code>3000</code> with an API server on port <code>8080</code>:</p>
<pre><code>relay = "wss://relay.instawormhole.site"

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

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"
</code></pre>
<h3>Top-Level Configuration Keys</h3>
<p>At the root of <code>instawormhole.toml</code>, you specify the relay endpoint that the connector uses:</p>
<ul>
<li><strong><code>relay</code>:</strong> Specifies the InstaWormhole relay endpoint using plain double-quoted strings, set to <code>"wss://relay.instawormhole.site"</code>.</li>
</ul>
<h3>Tunnel Entry Keys (<code>[[tunnel]]</code>)</h3>
<p>Each <code>[[tunnel]]</code> section defines an individual tunnel started by the connector process, with a maximum of 10 tunnels in one file:</p>
<ul>
<li><strong><code>name</code>:</strong> A label for the tunnel entry (for example, <code>"web"</code> or <code>"api"</code>).</li>
<li><strong><code>origin</code>:</strong> The local loopback address and port where your service is listening (for example, <code>"127.0.0.1:3000"</code> or <code>"127.0.0.1:8080"</code>).</li>
<li><strong><code>tunnel</code> (optional):</strong> 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.</li>
</ul>
<table>
<thead>
<tr>
<th>Key</th>
<th>Level</th>
<th>Required</th>
<th>Description</th>
<th>Example</th>
</tr>
</thead>
<tbody><tr>
<td><code>relay</code></td>
<td>Root</td>
<td>Yes</td>
<td>InstaWormhole relay endpoint string</td>
<td><code>"wss://relay.instawormhole.site"</code></td>
</tr>
<tr>
<td><code>name</code></td>
<td><code>[[tunnel]]</code></td>
<td>Yes</td>
<td>Label for the tunnel entry</td>
<td><code>"web"</code></td>
</tr>
<tr>
<td><code>origin</code></td>
<td><code>[[tunnel]]</code></td>
<td>Yes</td>
<td>Local loopback address and port</td>
<td><code>"127.0.0.1:3000"</code></td>
</tr>
<tr>
<td><code>tunnel</code></td>
<td><code>[[tunnel]]</code></td>
<td>No</td>
<td>Durable tunnel ID from the dashboard</td>
<td><code>"0199aa00-0000-7000-8000-00000000000c"</code></td>
</tr>
</tbody></table>
<h2>Step-by-Step: Running Your Frontend and API Together</h2>
<p>Follow these steps to set up and run both your frontend and backend services through a single <code>instawormhole.toml</code> file.</p>
<h3>1. Start Your Local Frontend and Backend Servers</h3>
<p>Before running the connector, start both local applications and confirm they are listening on loopback addresses:</p>
<ol>
<li>Start your frontend server on a loopback address such as <code>127.0.0.1:3000</code> or <code>localhost:3000</code>.</li>
<li>Start your backend API server on a loopback address such as <code>127.0.0.1:8080</code>.</li>
</ol>
<p>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.</p>
<h3>2. Create Your <code>instawormhole.toml</code> File</h3>
<p>Create a file named <code>instawormhole.toml</code> in the folder where you will run the connector:</p>
<pre><code>relay = "wss://relay.instawormhole.site"

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

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"
</code></pre>
<p>If you work in a shared repository and include durable tunnel IDs or personal configuration details in <code>instawormhole.toml</code>, add <code>instawormhole.toml</code> to <code>.gitignore</code> or keep a sanitized example file in version control.</p>
<h3>3. Sign In Your Computer (<code>--stored-device</code>)</h3>
<p>As documented in <a href="https://instawormhole.com/docs/connect/run-the-connector">Expose localhost:3000 with npx: Run Options</a> and <a href="https://instawormhole.com/docs/connect/several-tunnels">Run several tunnels from one file</a>, <code>--config</code> requires <code>--stored-device</code> so the connector uses the sign-in saved for your device. Follow the device sign-in steps in the <a href="https://instawormhole.com/docs">InstaWormhole documentation</a> if this computer has not yet been signed in. On Linux, <code>--store file</code> can also be added to commands to keep credentials in a private file instead of the operating system store.</p>
<h3>4. Launch All Tunnels With One Command</h3>
<p>Run the connector from the directory containing your configuration file:</p>
<pre><code>npx @instawormhole/connector run --config instawormhole.toml --stored-device
</code></pre>
<p>The connector starts every tunnel defined in <code>instawormhole.toml</code> 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.</p>
<h3>5. Point Your Frontend to the Public API Tunnel URL</h3>
<p>Once the connector prints the public addresses for your <code>web</code> and <code>api</code> tunnels, update your frontend environment variables (such as <code>NEXT_PUBLIC_API_URL</code> or <code>VITE_API_BASE_URL</code>) so browser requests from the public frontend address target the public <code>api</code> tunnel address rather than a local-only port unreachable from external devices or third-party services.</p>
<p>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.</p>
<h2>Connecting Durable Tunnels From the Dashboard</h2>
<p>When you omit the <code>tunnel</code> key in a <code>[[tunnel]]</code> 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 <a href="https://instawormhole.com/docs/connect/run-the-connector">Expose localhost:3000 with npx: Run Options</a> and <a href="https://instawormhole.com/">InstaWormhole</a>:</p>
<ul>
<li><strong>Stable addresses:</strong> A durable tunnel keeps its address across sessions and automatic reconnections.</li>
<li><strong>Access protection:</strong> Durable tunnels can be protected with access controls such as passwords, access tokens, email codes, or IP lists.</li>
<li><strong>Request inspection:</strong> Durable tunnels show their requests in the request inspector.</li>
</ul>
<p>To connect a <code>[[tunnel]]</code> entry in <code>instawormhole.toml</code> to a durable tunnel:</p>
<ol>
<li>Locate or create the durable tunnel in the InstaWormhole dashboard and copy its tunnel ID.</li>
<li>Add the optional <code>tunnel</code> key with that ID to the matching <code>[[tunnel]]</code> block in <code>instawormhole.toml</code>.</li>
</ol>
<pre><code>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"
</code></pre>
<p>When you run <code>npx @instawormhole/connector run --config instawormhole.toml --stored-device</code>, 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.</p>
<h2>Scaling Up: Running Up to 10 Services Together</h2>
<p>A single <code>instawormhole.toml</code> 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:</p>
<pre><code>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"
</code></pre>
<p>Pressing <code>Ctrl+C</code> 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.</p>
<h2>Validation Rules and <code>config_invalid</code> Watch-Outs</h2>
<p>According to <a href="https://instawormhole.com/docs/connect/several-tunnels">Run several tunnels from one file</a>, if something is wrong with the configuration file, the connector stops with the error <code>config_invalid</code>. The file format is intentionally strict to protect you from a typo that could expose something unexpected.</p>
<h3>1. Loopback-Only Origins</h3>
<p>Every <code>origin</code> in <code>instawormhole.toml</code> must be a loopback address (such as <code>127.0.0.1:3000</code>, <code>localhost:5173</code>, or <code>[::1]:3000</code>). A configuration file or <code>--origin</code> value that specifies a non-loopback address is refused.</p>
<ul>
<li><strong>Valid origin:</strong> <code>origin = "127.0.0.1:3000"</code></li>
<li><strong>Invalid origin:</strong> <code>origin = "192.168.1.50:3000"</code> (non-loopback address is refused)</li>
<li><strong>Invalid origin:</strong> <code>origin = "example.com:80"</code> (non-loopback host is refused)</li>
</ul>
<h3>2. Up to 10 Tunnels Per File</h3>
<p>A single configuration file supports up to 10 tunnels. Defining more than 10 tunnels in one file triggers <code>config_invalid</code>. If you need to manage additional tunnels across separate sets of services, split them into multiple configuration files and run separate connector commands.</p>
<h3>3. Strict Allowed Keys, Plain Double-Quoted Strings, and Comments</h3>
<p>The documentation specifies that only the documented keys are allowed, using plain double-quoted strings and <code>#</code> comments. Unknown keys, malformed syntax, or invalid values cause the connector to stop with <code>config_invalid</code>, and the message names the key or value to fix. Also note from <a href="https://instawormhole.com/docs/connect/run-the-connector">Expose localhost:3000 with npx: Run Options</a> that the connector refuses an option given twice rather than letting the last occurrence win.</p>
<table>
<thead>
<tr>
<th>Configuration Mistake</th>
<th>Why It Fails</th>
<th>How to Fix It</th>
</tr>
</thead>
<tbody><tr>
<td>Non-loopback <code>origin</code> address</td>
<td>Every <code>origin</code> must be a loopback address</td>
<td>Use a loopback address such as <code>127.0.0.1:3000</code> or <code>localhost:3000</code></td>
</tr>
<tr>
<td>More than 10 tunnels in one file</td>
<td>One file opens up to 10 tunnels</td>
<td>Keep total tunnels in <code>instawormhole.toml</code> to 10 or fewer, or split into another file</td>
</tr>
<tr>
<td>Unallowed keys or syntax errors</td>
<td>File format allows only documented keys, plain double-quoted strings, and <code>#</code> comments</td>
<td>Fix the key or value named in the <code>config_invalid</code> message</td>
</tr>
<tr>
<td>Duplicate CLI options</td>
<td>Connector refuses an option given twice</td>
<td>Pass each flag once per command invocation</td>
</tr>
</tbody></table>
<h2>Troubleshooting Checklist</h2>
<p>When a multi-tunnel setup needs debugging, work through these checks using the <a href="https://instawormhole.com/docs">InstaWormhole documentation</a>:</p>
<ul>
<li><strong>Connector exits with <code>config_invalid</code>:</strong> Inspect the error message for the key or value named, confirm every <code>origin</code> 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 <code>#</code> comments.</li>
<li><strong>App does not respond or times out:</strong> Verify your local frontend and API servers are running on their configured loopback ports, and check <code>--origin-timeout</code> 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).</li>
<li><strong>Cross-origin requests between frontend and API tunnels:</strong> 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.</li>
<li><strong>Sign-in or diagnostic issues:</strong> Confirm the computer is signed in when using <code>--stored-device</code>, inspect traffic in the request inspector on durable tunnels, and use Tunnel Doctor or the diagnostic documentation in <a href="https://instawormhole.com/docs">InstaWormhole Docs</a> to check DNS, TLS, connector, protection, and app layers.</li>
</ul>
<h2>Summary of Commands and Configuration</h2>
<p>Keep this minimal configuration and command handy when setting up a frontend and API together:</p>
<pre><code>relay = "wss://relay.instawormhole.site"

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

[[tunnel]]
name = "api"
origin = "127.0.0.1:8080"
</code></pre>
<p>Launch the configured tunnels with:</p>
<pre><code>npx @instawormhole/connector run --config instawormhole.toml --stored-device
</code></pre>
<p>Using <code>instawormhole.toml</code> 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 <a href="https://instawormhole.com/docs">InstaWormhole documentation</a>.</p>
<hr />
<p><em>Originally published at <a href="https://instawormhole.com/blog/run-a-frontend-and-api-together-from-one-tunnel-file">https://instawormhole.com/blog/run-a-frontend-and-api-together-from-one-tunnel-file</a></em></p>
]]></content:encoded></item><item><title><![CDATA[Expose a Local MCP Server Safely With Access Tokens]]></title><description><![CDATA[Expose a local MCP server over HTTPS for AI clients using Streamable HTTP or SSE with bearer tokens, X-InstaWormhole-Token headers, and zero browser]]></description><link>https://instawormhole.hashnode.dev/expose-a-local-mcp-server-safely-with-access-tokens</link><guid isPermaLink="true">https://instawormhole.hashnode.dev/expose-a-local-mcp-server-safely-with-access-tokens</guid><category><![CDATA[networking]]></category><category><![CDATA[Devops]]></category><category><![CDATA[webdev]]></category><category><![CDATA[Security]]></category><category><![CDATA[programming]]></category><dc:creator><![CDATA[InstaWormhole]]></dc:creator><pubDate>Thu, 19 Nov 2026 02:12:10 GMT</pubDate><enclosure url="https://cdn.hashnode.com/uploads/covers/6afd4935db431bf520bd4a87/7fae790f-ebc5-4f9f-826c-cef0e43cf23f.png" length="0" type="image/jpeg"/><content:encoded><![CDATA[<p>When you build a local Model Context Protocol (MCP) server on your machine, everything works smoothly while you talk to it from the same computer. The friction starts when an AI client outside your network, such as a remote agent runtime or a cloud-hosted client, needs to reach your server. Those clients typically connect over <strong>Streamable HTTP</strong> or <strong>server-sent events</strong>.</p>
<p>Opening a public address is the easy part. Protecting it without breaking automated clients is the real challenge. A browser password prompt stops human visitors, but many AI clients cannot answer one. That is why a token-protected HTTPS tunnel suits local MCP workflows.</p>
<p>With <strong>InstaWormhole</strong>, you connect a tunnel to your local MCP server, create an <strong>access token</strong> (available on <strong>Starter and higher</strong>), and have your AI client send that token in a request header. The tunnel checks the token and does not pass it on to your server, so your MCP server can keep its own authentication.</p>
<h2>Why a Local MCP Server Needs Protection</h2>
<p>Anyone who knows a tunnel’s address can reach your MCP server unless you protect it. That matters because an MCP server can read files or run commands on your computer.</p>
<blockquote>
<p>Because an MCP server can read files or run commands, treat the tunnel address and its access token as sensitive. Share them only with AI clients you trust.</p>
</blockquote>
<p>Three practical points shape the setup:</p>
<ul>
<li><strong>Many AI clients cannot answer a browser password prompt.</strong> An access token, which the client sends as a header, is the better fit.</li>
<li><strong>A stable address helps.</strong> A quick address from the connector is temporary and random, while a durable tunnel keeps the same address across reconnects, sleep and network changes. Access tokens apply to durable tunnels.</li>
<li><strong>Streaming must stay intact.</strong> The connector forwards streaming responses as they are produced, which is what Streamable HTTP and server-sent events need. InstaWormhole has not published a list of AI clients it has tested, so test your own client.</li>
</ul>
<h2>How the Connection Works</h2>
<p>The connector on your computer opens an outbound connection to InstaWormhole, so you do not open a port on your router or change your firewall for incoming traffic. A request then travels like this:</p>
<ol>
<li>An AI client sends an HTTPS request to your tunnel’s address plus your MCP path.</li>
<li>InstaWormhole’s edge checks the tunnel’s rules, including its token.</li>
<li>If the request passes, the relay hands it to your connector over the connection the connector opened.</li>
<li>The connector passes it to your MCP server on a loopback address and sends the answer back along the same path.</li>
</ol>
<p>If the check cannot be made, the edge refuses the request instead of letting it through.</p>
<h2>Step-by-Step: Expose a Local MCP Server With an Access Token</h2>
<p>The InstaWormhole guide estimates about 10 minutes for this setup.</p>
<h3>Step 1: Start Your Server and Connect a Tunnel</h3>
<p>Start your MCP server on a local port, such as <code>8000</code>, then connect a tunnel to that port:</p>
<pre><code>npx @instawormhole/connector 8000
</code></pre>
<p>This form opens a temporary address. Because access tokens need a durable tunnel, create a tunnel in the dashboard and use the durable tunnel command it gives you for a stable, protectable address. The connector prints the tunnel’s address once connected.</p>
<p>A few requirements to check first:</p>
<ul>
<li>Your server must answer plain HTTP on a loopback address, such as <code>127.0.0.1:8000</code>. A local server that only accepts HTTPS is not supported.</li>
<li>The <code>npx</code> command needs Node.js 20 or later.</li>
</ul>
<h3>Step 2: Create an Access Token</h3>
<p>Access tokens are available on Starter and higher plans. In the dashboard:</p>
<ol>
<li>Open the tunnel and choose <strong>Access token</strong>, then <strong>Create token</strong>.</li>
<li>Copy the token and store it in a password manager or secret store.</li>
</ol>
<p>Two details are worth knowing before you close the dialog:</p>
<ul>
<li><strong>The token is shown once.</strong> It cannot be read back later. If you lose it, create a new one with <strong>Replace access token</strong>, and the old token stops working.</li>
<li><strong>Creating or replacing a token ends the tunnel’s live connection.</strong> Your connector reconnects on its own.</li>
</ul>
<p>Treat the token like a password. Anyone who has it can open the tunnel, so keep it out of repositories, screenshots and chats.</p>
<h3>Step 3: Give Your AI Client the URL and Token</h3>
<p>Give the client your tunnel’s address plus the path your server uses, for example <code>https://example.instawormhole.site/mcp</code>. Have it send the token in one of two ways:</p>
<ul>
<li>The <code>X-InstaWormhole-Token</code> header</li>
<li>A bearer token in the <code>Authorization</code> header</li>
</ul>
<p>You can test both from a terminal:</p>
<pre><code>curl -H "X-InstaWormhole-Token: &lt;token&gt;" https://example.instawormhole.site/mcp
</code></pre>
<pre><code>curl -H "Authorization: Bearer &lt;token&gt;" https://example.instawormhole.site/mcp
</code></pre>
<p>Replace <code>&lt;token&gt;</code> with your token and <code>example</code> with your tunnel’s name. When it works, your client connects and lists the server’s tools.</p>
<p>To confirm protection is active, send the same request without the header. The tunnel answers <code>401</code>.</p>
<h2>Why the Token Is Not Passed to Your Server</h2>
<p>The tunnel checks the access token and does not pass it to your app. This keeps two layers of authentication separate:</p>
<ul>
<li><strong>The tunnel controls who gets through.</strong> The token proves to InstaWormhole that the caller may use the tunnel.</li>
<li><strong>Your server controls what callers can do.</strong> It can keep enforcing its own authentication without colliding with the tunnel’s credential.</li>
</ul>
<h2>Choosing the Right Access Control</h2>
<p>A tunnel has one access mode at a time: anyone, a password, a token or an email code. An IP allow or deny list works on top of any of them. Password, token, email code and IP lists all need Starter or higher.</p>
<table>
<thead>
<tr>
<th>Control</th>
<th>What it does</th>
<th>Best fit</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Access token</strong></td>
<td>Requires a secret token in a request header</td>
<td>Scripts, AI clients and webhook providers that cannot type a password</td>
</tr>
<tr>
<td><strong>Password</strong></td>
<td>The browser asks for a password before the request reaches your app</td>
<td>Browser visitors, such as a client reviewing a demo</td>
</tr>
<tr>
<td><strong>Email code</strong></td>
<td>Only listed email addresses can open the tunnel, each with an emailed six-digit code</td>
<td>Named people who should not share one password</td>
</tr>
<tr>
<td><strong>IP allow or deny list</strong></td>
<td>Allows only the networks you list, or everyone except them</td>
<td>Services that always call from known addresses</td>
</tr>
</tbody></table>
<p>For AI clients that connect over Streamable HTTP or server-sent events, an access token is the direct choice, since these clients send headers rather than completing browser prompts.</p>
<h2>Troubleshooting</h2>
<h3>Requests Are Refused With a 401</h3>
<p>If a request omits the token, the tunnel answers <code>401</code>. If requests that carry the token are still refused, check that the header name is spelled exactly <code>X-InstaWormhole-Token</code>, or that the <code>Authorization</code> header starts with <code>Bearer</code> and a space.</p>
<h3>The Token Stops Working After You Replace It</h3>
<p>Replacing a token stops the old one immediately. Update your AI client with the new token. The tunnel’s live connection also ends briefly while the connector reconnects.</p>
<h3>CONNECTOR_UNAVAILABLE</h3>
<p>The connector is recorded as connected but did not take the request. Restart it with <code>Ctrl+C</code>, then run your connector command again.</p>
<h3>Your Server Is Unreachable or Slow</h3>
<ul>
<li><strong>Check the port.</strong> Make sure your server is running and that the origin address in your connector command matches the port it listens on.</li>
<li><strong>Slow tool calls.</strong> By default, the connector waits 10 minutes for a response to start and 2 minutes with no data. You can change this with <code>--origin-timeout</code>, which accepts 1 to 3600 seconds.</li>
</ul>
<h3>Rate and Transfer Limits</h3>
<p>Tunnels answer <code>429</code> when they exceed their plan’s limits. When a tunnel gets more requests a minute than its plan allows, the relay answers <code>429</code> until the minute passes. When the monthly transfer allowance is used up, tunnels answer <code>429</code> until the first of next month (UTC).</p>
<p>Limits on the plans that include access tokens, according to the plan comparison:</p>
<table>
<thead>
<tr>
<th>Plan</th>
<th>Price</th>
<th>Requests a minute per tunnel</th>
<th>Transfer a month</th>
</tr>
</thead>
<tbody><tr>
<td>Starter</td>
<td>$4.99 a month</td>
<td>600</td>
<td>50 GB</td>
</tr>
<tr>
<td>Pro</td>
<td>$9.99 a month</td>
<td>1,200</td>
<td>200 GB</td>
</tr>
<tr>
<td>Team</td>
<td>$19.99 a month</td>
<td>2,400</td>
<td>500 GB</td>
</tr>
<tr>
<td>Business</td>
<td>$39.99 a month</td>
<td>4,800</td>
<td>1 TB</td>
</tr>
</tbody></table>
<p>For comparison, the Free plan allows 120 requests a minute per tunnel and 5 GB of transfer a month, but it does not include access tokens. Prices are in US dollars before any tax.</p>
<h3>Check Each Layer</h3>
<p>On a durable tunnel, choose <strong>Run Tunnel Doctor</strong> in the dashboard. It checks, in the order a request travels, address lookup (DNS), secure connection (TLS), tunnel state, connector, access protection, your app, and a request through the public address. You can run it once every 10 seconds per tunnel. It sends no credentials, so it cannot test past a token or password.</p>
<p>You can also use <strong>Open request inspector</strong> on a durable tunnel to see each request’s status and whether your app or InstaWormhole answered it. The inspector keeps a request record for 24 hours.</p>
<h2>Checklist Before You Share an MCP Endpoint</h2>
<ol>
<li>Confirm your MCP server is running locally, answers plain HTTP, and serves the path you expect.</li>
<li>Connect a durable tunnel using the command from your dashboard.</li>
<li>Create an access token on a Starter or higher plan and store it securely.</li>
<li>Configure your AI client with your tunnel’s address plus the MCP path, and the token in <code>X-InstaWormhole-Token</code> or <code>Authorization: Bearer &lt;token&gt;</code>.</li>
<li>Send a request without the token and confirm it is refused, then confirm your client lists the server’s tools through the tunnel.</li>
</ol>
<p>Exposing a local MCP server does not have to mean leaving a public address open to anyone. A durable tunnel with an access token lets AI clients reach your server over HTTPS, while your server keeps its own authentication.</p>
<p>For full details, see the <a href="https://instawormhole.com/docs/integrate/ai-and-mcp-servers">InstaWormhole MCP server guide</a> and the <a href="https://instawormhole.com/docs/protect/use-an-access-token">access token documentation</a>.</p>
<hr />
<p><em>Originally published at <a href="https://instawormhole.com/blog/expose-a-local-mcp-server-safely-with-access-tokens">https://instawormhole.com/blog/expose-a-local-mcp-server-safely-with-access-tokens</a></em></p>
]]></content:encoded></item></channel></rss>