How to Expose a Local API to the Internet for Development and Testing

Why localhost is not publicly reachable

An API bound to 127.0.0.1 or localhost accepts connections originating on the same machine. A phone using mobile data, a cloud webhook provider, and a remote teammate cannot route requests to that loopback address. Even a private LAN address such as 192.168.1.50 is not normally routable from the public internet.

Traditional inbound exposure can involve a public IP address, router port forwarding, firewall rules, and careful control of the service listening behind those rules. That can be appropriate for deliberately managed infrastructure, but it is often inconvenient for a temporary development workflow. It may also be unavailable when the developer cannot administer the router or is behind carrier-grade NAT.

With Localtonet, the client application on your device establishes an outbound connection to a Localtonet relay server. The running tunnel publishes either a public URL or a public host and port, depending on the selected tunnel type. Requests arriving at that public endpoint travel through the relay and the established client connection to the configured local IP address and port.

Prerequisites and preflight checks

Prepare the API and its security controls before creating a public path to it. This local-first approach separates application failures from tunnel failures and avoids exposing a half-configured service.

A locally working API

Start the API using its normal development command and identify its listening address and port. Test a harmless health or example endpoint from the same machine. If this request fails, fix the application before configuring Localtonet.

curl -i http://127.0.0.1:3000/api/hello

A successful response should include the expected status code, headers, and body. Prefer a dedicated health endpoint or an endpoint backed by disposable test data. Do not use production credentials or create real orders, messages, payments, or customer records merely to verify connectivity.

Required runtime and framework dependencies

Install a currently supported runtime for the framework you intend to use. Record the actual runtime and dependency versions in your project lockfile or development documentation so teammates can reproduce the environment. The examples below show dependency installation and startup, but your existing project may already define these through a package manager, container, or task runner.

A Localtonet account and connected client

You need a Localtonet account, the Localtonet client application installed for the operating system that will run the tunnel, and a device-specific authentication token. Install and run the client on a device that can reach the target API. The token identifies that client device and must be kept secret.

The available client installation path and user interface can vary by operating system and client version. Use the current download and installation instructions presented by Localtonet rather than copying an unverified command from an older tutorial. This guide intentionally does not provide a guessed CLI flag.

An available relay selection

Select an available Localtonet relay server or region when configuring the tunnel. Server codes and availability can change and may vary by account or plan, so obtain the current value from the product instead of hardcoding a server name from an example.

Application security prepared in advance

• Enable API authentication for every route that does not intentionally need anonymous access.
• Use a test account with only the permissions needed for the scenario.
• Configure CORS for the exact development origin when a browser-based client will call the API.
• Confirm how the framework handles forwarded scheme, host, and client-address headers.
• Remove secrets, session tokens, authorization headers, and personal data from debug logs.
• Apply request-size limits, timeouts, and rate limiting suitable for an internet-facing test endpoint.
• Prepare a shutdown plan so the tunnel is stopped promptly after testing.

Choose the right tunnel type

Choose according to the protocol actually spoken by the client and server, not merely the programming framework. REST and ordinary JSON APIs are normally HTTP applications. WebSockets begin with an HTTP upgrade request. gRPC commonly uses HTTP/2. Those details mean WebSockets and gRPC should not automatically be classified as generic raw TCP services.

HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. These process types serve the same content at a public HTTPS address. Availability can vary by plan or current product configuration. If you use a custom domain, follow the current Localtonet DNS documentation rather than relying on old record values.

Create and verify a small local API

Skip this section if your API already works locally. Otherwise, use one of these minimal examples to establish a known-good endpoint. Each example returns non-sensitive JSON and can be verified before any tunnel is created.

Node.js with Express

Install a currently supported Node.js LTS release, confirm it with node --version, and initialize a project. The following CommonJS example installs Express as a project dependency.

mkdir local-api-example
cd local-api-example
npm init -y
npm install express

const express = require("express");

const app = express();
const port = 3000;

app.use(express.json());

app.get("/api/hello", (req, res) => {
  res.json({ message: "Hello from the local API" });
});

app.post("/api/echo", (req, res) => {
  res.status(200).json({ received: req.body });
});

app.listen(port, "127.0.0.1", () => {
  console.log(`API listening on http://127.0.0.1:${port}`);
});

Save the code as server.js, start it, and test both routes:

node server.js
curl -i http://127.0.0.1:3000/api/hello
curl -i -X POST http://127.0.0.1:3000/api/echo \
  -H "Content-Type: application/json" \
  --data '{"test":"local-only","sequence":1}'

Keep the loopback binding when the Localtonet client runs on this machine. If a separate LAN device runs the client, choose an appropriate reachable binding and apply host firewall rules. Add CORS middleware only when a browser origin needs cross-origin access, and allow the exact origin rather than reflecting arbitrary origins. Do not enable credentialed CORS with a wildcard origin.

Express does not automatically know which forwarding headers are trustworthy. If application logic depends on the original scheme, host, or client address, configure trusted proxy behavior only for a verified proxy path. Do not blindly trust every proxy source, because a false trust configuration can let callers influence security-sensitive values.

Python with FastAPI

Use a supported Python 3 release and create a virtual environment so dependencies remain isolated from the system installation.

mkdir fastapi-local-example
cd fastapi-local-example
python -m venv .venv
source .venv/bin/activate
python -m pip install fastapi uvicorn

On Windows, activate the virtual environment using the activation command appropriate to PowerShell or Command Prompt. Save this application as main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/api/hello")
def hello():
    return {"message": "Hello from the local API"}

@app.post("/api/echo")
def echo(payload: dict):
    return {"received": payload}

python -m uvicorn main:app --host 127.0.0.1 --port 8000
curl -i http://127.0.0.1:8000/api/hello
curl -i -X POST http://127.0.0.1:8000/api/echo \
  -H "Content-Type: application/json" \
  --data '{"test":"local-only","sequence":1}'

If a browser frontend uses this API, configure FastAPI's CORS middleware with the exact public frontend origin and the methods and headers it needs. Proxy and forwarded-header settings affect generated URLs, redirects, scheme detection, and client-address handling. Enable them only for the known deployment path, especially when authentication or secure-cookie decisions depend on the perceived request scheme.

Python with Flask

mkdir flask-local-example
cd flask-local-example
python -m venv .venv
source .venv/bin/activate
python -m pip install flask

Save the following as app.py:

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.get("/api/hello")
def hello():
    return jsonify(message="Hello from the local API")

@app.post("/api/echo")
def echo():
    return jsonify(received=request.get_json(silent=False))

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)

python app.py
curl -i http://127.0.0.1:5000/api/hello
curl -i -X POST http://127.0.0.1:5000/api/echo \
  -H "Content-Type: application/json" \
  --data '{"test":"local-only","sequence":1}'

Flask's built-in development server is suitable for this focused development test, not as a general production deployment recommendation. If Flask rejects an unexpected host or generates an incorrect external URL, review the application's host validation and proxy configuration. Apply forwarded-header middleware only with a narrowly understood proxy count and trust boundary.

Go standard library

Install a supported Go release and confirm it with go version. This example uses only the standard library.

mkdir go-local-example
cd go-local-example
go mod init example.local/local-api

package main

import (
	"encoding/json"
	"log"
	"net"
	"net/http"
	"time"
)

func hello(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{
		"message": "Hello from the local API",
	})
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/api/hello", hello)

	server := &http.Server{
		Addr:              "127.0.0.1:8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
		BaseContext: func(net.Listener) context.Context {
			return context.Background()
		},
	}

	log.Fatal(server.ListenAndServe())
}

Add "context" to the import list for the example above, then start and test it:

go run .
curl -i http://127.0.0.1:8080/api/hello

Keep explicit server timeouts in internet-reachable development services. Validate allowed hosts in application code when host-based routing or security decisions depend on the request host. Treat forwarded headers as untrusted input unless they arrive through a verified proxy boundary.

Configure a Localtonet HTTP tunnel

Use this workflow for REST APIs, JSON endpoints, GraphQL, browser-facing development APIs, webhooks, and OAuth callback routes. The exact labels and layout can vary by current client or dashboard version, so the instructions focus on the documented fields and lifecycle rather than an unverified navigation path.

The following placeholder uses the reserved .example domain. Replace it with the exact address assigned to your running tunnel:

curl -i https://your-assigned-host.example/api/hello

curl -i -X POST https://your-assigned-host.example/api/echo \
  -H "Content-Type: application/json" \
  --data '{"test":"public-path","sequence":2}'

Compare the public response with the local response. Check the API's own logs to confirm that the expected method and path arrived exactly once. If the public request fails, keep the local API running and follow the systematic troubleshooting section below instead of changing multiple settings at once.

Configure a Localtonet TCP tunnel

Use a TCP tunnel for a service that genuinely requires raw TCP forwarding. This is not the automatic choice for every protocol whose implementation ultimately uses TCP. WebSockets normally begin as HTTP, and gRPC commonly depends on HTTP/2, so test their protocol-specific requirements before selecting a tunnel.

A basic port-connectivity tool can show that a TCP connection opens, but it does not prove that the application protocol works. Complete the test with the same client library or application that will use the service. For TLS-based or hostname-sensitive protocols, also verify server-name and certificate expectations.

Configure common development and testing scenarios

Webhook delivery to a local handler

Create an HTTP tunnel to the locally verified webhook route, then register the full public path with the provider. For example, if the handler is /webhooks/provider, register the assigned public origin plus that exact path. Use the provider's test mode and test events whenever available.

Verify the provider's signature before parsing or acting on the event. Many webhook schemes sign the exact raw request bytes. Parsing JSON and serializing it again can change whitespace or ordering and invalidate the signature. Capture the raw body using the framework's documented mechanism, read the signature and timestamp headers, compute or verify the signature with the provider's official library where available, and reject invalid or stale messages before performing side effects.

Make the handler idempotent because providers may retry after a timeout or non-success response. Store the provider's event identifier and avoid applying the same event twice. Return the expected success status promptly, then move slow work to a controlled background process if the integration supports that architecture. Never log the webhook signing secret or full sensitive payload.

Mobile application testing

Put the assigned public HTTPS origin in a development-only mobile configuration. Do not compile production secrets into the application. Authenticate the mobile test user normally and use a narrowly privileged test account.

Test from the network that matters, such as mobile data or a separate Wi-Fi connection. Verify DNS resolution, certificate acceptance, redirects, API authentication, request timeouts, and error handling. If the mobile app stores the base URL at build time, rebuild or refresh its development configuration after the endpoint changes.

OAuth callback development

Register the complete assigned callback URI with the OAuth provider, including the scheme, host, path, port if applicable, and any provider-supported query requirements. OAuth providers commonly require an exact redirect URI match. A different subdomain, missing path segment, trailing-slash difference, or HTTP versus HTTPS mismatch can cause rejection.

Generate a cryptographically strong, single-use state value before redirecting the browser, associate it with the initiating session, and validate it on return. For flows using PKCE, generate and protect the verifier according to the provider's requirements. Exchange authorization codes only on the appropriate trusted component, prevent code reuse, and avoid logging codes, tokens, client secrets, or complete callback URLs containing sensitive parameters.

An access screen designed for interactive browser users may not suit an OAuth provider callback or a machine-to-machine API request because those callers cannot complete an interactive login flow. Protect the application using OAuth protocol validation and API authorization appropriate to the callback rather than assuming a browser-oriented access layer will work for every caller.

Sharing an API with a teammate

Share only the endpoint and temporary test credentials the teammate needs. Use least-privilege accounts, isolate test data, and agree on the available testing window. If a frontend is hosted on a different origin, add that exact origin to the API's CORS allowlist and allow only the necessary methods and headers.

Ask the teammate to report the request time, method, path, status, and a non-sensitive correlation identifier. This information is much more useful than a screenshot saying that the API failed. Remove their temporary authorization when the session ends and stop the tunnel.

Remote automation or AI-agent calls

A cloud workflow, remote automation system, or AI agent can call an HTTP API only while the local client remains connected and the tunnel remains running. Give the caller a dedicated API credential with narrow scopes, apply request and response size limits, and validate all inputs. For tools that can trigger side effects, require explicit authorization and design operations to be safely retried.

Do not put the Localtonet device token in the remote tool. The remote caller needs the public API endpoint and its own application credential, not the client device's tunnel credential. Treat prompts, generated arguments, uploaded files, and callback payloads as untrusted input.

CI and remote test runners

A remote CI runner can test a laptop-hosted API only if that laptop is already online, the correct Localtonet client is connected, the tunnel is running, and the endpoint has been supplied securely to the test job. An unrelated CI job cannot be assumed to control or start a tunnel on a developer laptop.

Keep the endpoint in protected CI configuration, not in the repository. Use a short-lived test credential, restrict the API to a disposable dataset, and prevent concurrent jobs from modifying the same records. Add readiness checks before the suite, bounded retries for transient startup conditions, and cleanup after the run. For repeatable automated testing, a controlled test host or isolated ephemeral environment may be more reliable than a sleeping developer workstation.

Security checklist for a publicly reachable development API

CORS is a browser policy, not API authentication

Configure CORS only for browser applications that require cross-origin calls. Allow the exact frontend origin and necessary methods and headers. If cookies or browser credentials are used, configure credentials deliberately and do not combine them with a wildcard origin. Non-browser clients can call an endpoint regardless of browser CORS enforcement, so authentication and authorization remain mandatory.

Forwarded headers require a trust decision

Reverse-proxy paths may provide information about the original host, scheme, or client address through forwarded headers. Frameworks vary in whether they ignore, trust, or transform those values. Trusting arbitrary forwarded headers can affect secure-cookie logic, redirect construction, IP-based controls, and audit records.

Configure proxy trust only when you understand which component supplies the headers and which source is allowed to do so. The current evidence does not provide relay address ranges for a source-based trust rule, so do not invent them. Where precise trust cannot be established, avoid using forwarded client addresses as an authentication or authorization signal.

Host validation and absolute URLs

Some development servers accept only expected hostnames. A request through the tunnel uses the public host, which can trigger an invalid-host response even though direct localhost requests work. Add only the assigned development host to the application's allowed-host configuration. Do not disable host validation globally merely to make a test pass.

Applications that generate absolute redirects, password-reset links, webhook URLs, or OAuth callback URLs must use the intended public origin. Configure that origin explicitly where the framework supports it, then verify generated links. Avoid constructing security-sensitive URLs from an unvalidated Host header.

Browser access layers versus machine clients

A protection layer that asks users to sign in through an interactive browser can be useful for a human preview, but webhook senders, OAuth callbacks, mobile APIs, CI jobs, and other machine clients may not be able to complete that interaction. Use API keys, signed webhooks, OAuth client credentials, mutual authentication where supported by the application, or another machine-compatible method appropriate to the integration. Availability of specific tunnel-level access options can vary, so confirm current product and plan behavior before designing around one.

Verify, operate, rotate, and shut down the tunnel

Use a layered verification sequence

1. Confirm the API process is running.
2. Call the target address and port directly from the Localtonet client device.
3. If the API is on another LAN host, call it from the client device using the exact configured LAN address.
4. Confirm the Localtonet client is connected with the intended device token.
5. Confirm the tunnel has been explicitly started and is shown as running.
6. Call the assigned endpoint from a separate network.
7. Correlate the public request with the API's local log entry.
8. Verify the response content, headers, redirects, authentication, and side effects.

This sequence identifies the failing layer without guesswork. A failed local call indicates an application or binding problem. A successful local call followed by a failed public call points toward the target configuration, client connection, tunnel state, protocol choice, or application handling of the public request.

Monitor the dependencies that keep the endpoint available

The public endpoint depends on three active components: the API process, the selected Localtonet client connection, and the running tunnel. Closing the API, disconnecting the client, changing networks, or allowing the machine to sleep can interrupt access. A tunnel intended for a scheduled test should be checked shortly before the test begins rather than assumed to remain available.

Use platform-wide Token/Tunnel webhooks only if you need notifications when a token or tunnel in a selected Token Group becomes Connected or Disconnected. Those notifications carry tunnel or token lifecycle information. They are separate from File Server file-event webhooks and do not report API request payloads.

Handle endpoint changes as configuration changes

Keep the assigned public origin in an environment-specific configuration value. If a tunnel is deleted, recreated, or assigned a different endpoint, update mobile builds, webhook registrations, OAuth redirect URI allowlists, remote automation settings, teammate configuration, and CI secrets as applicable.

Never assume that a custom domain, selected subdomain, or public port is available on every plan or that its behavior never changes. Check the current product options and DNS instructions. After any endpoint change, rerun both local and external verification.

Shut down cleanly

Troubleshooting a local API tunnel

Diagnose with logs from both ends

Start with the API's own access and error logs. If no request appears, the failure is before the application. If a request appears with an error response, inspect the method, path, host, content type, authentication result, and exception. Add a non-sensitive correlation identifier to the request when possible so a remote tester can identify the matching local log entry.

Avoid logging complete authorization headers, cookies, OAuth parameters, webhook signatures, or request bodies containing personal information. A useful diagnostic log records timing, route, status, request size, and a safe identifier without becoming a second source of sensitive data.

Check HTTP and HTTPS assumptions

Confirm what the local service actually accepts. A plain HTTP server will reject a direct TLS handshake, while a TLS-only service will reject plain HTTP. Select the Localtonet tunnel option that matches the required public and local protocol behavior, and verify it using the current product documentation. Do not infer transport behavior from the framework name alone.

Check timeouts at every layer

A request can time out in the caller, the provider, the application server, a database client, or downstream code. Reproduce the handler locally with the same payload size and operation. Set explicit, bounded timeouts and return a prompt acknowledgement for webhook designs that support asynchronous processing. Increasing every timeout can hide a deadlock or dependency failure rather than solve it.

Frequently asked questions