Keep a Tunnel URL Stable Across Container Restarts

Separate the tunnel lifecycle from the container lifecycle

A stable development preview begins with a simple architectural decision: the Localtonet client and the application container should not share the same disposable lifecycle. Development containers are routinely stopped, rebuilt, replaced, or recreated after dependency and configuration changes. If the tunnel client runs inside that same container, every application rebuild also interrupts the client process and can encourage developers to create a new tunnel unnecessarily.

Instead, run the Localtonet client on the host operating system or on another persistent device that can reliably reach the published application port. The development container can then be treated as replaceable. It listens on an internal container port, Docker publishes that service on a predictable host port, and the Localtonet HTTP tunnel points to the host-side address and port.

A typical network path looks like this:

Public HTTPS address
        |
Localtonet relay
        |
Outbound Localtonet client connection
        |
Host target, for example 127.0.0.1:3000
        |
Docker published-port mapping
        |
Application listening inside the container

This design separates endpoint identity from application uptime. Rebuilding the container does not require the existing tunnel configuration to be deleted or recreated. While the container is unavailable, requests cannot reach the application. Once the replacement container starts listening behind the same published host port, the existing network path can work again.

Why a container IP address is usually the wrong target

Containers commonly receive addresses from a Docker-managed network. Those addresses belong to a particular container instance and can change when the container is recreated. A host process should not depend on such an address when a published port can provide a more stable boundary.

If the Localtonet client runs on the host, point the HTTP tunnel at the published host address and port, not at the current private address reported for the container. The container may change, but the host-side listening address can remain the same as long as the replacement container publishes the same port.

Three independent states determine whether the preview works

Prepare the host, container, and application

Before configuring the tunnel, identify the exact service boundary you want to expose. Do not begin with the public endpoint. First make the host-side application URL predictable and locally testable.

You need the following:

• A development application that can run inside a Docker or compatible development container.
• A known application port inside the container.
• A fixed, currently unused port on the host.
• A container port mapping from the selected host port to the application port.
• The Localtonet client installed and running on the host, or on another persistent device that can reach the host-side target.
• A Localtonet device authentication token selected through the supported client and dashboard workflow. Tokens are device-specific and must not be placed in source control, screenshots, logs, or example configuration.
• An available relay server or region selected from the current Localtonet dashboard rather than copied from an old guide.
• Browser developer tools and a local HTTP client such as curl for verification.

The examples below use container port 3000 and host address 127.0.0.1:3000 only to demonstrate the pattern. Replace them with the port your development server actually uses. Project defaults differ, and the correct port must come from your application's configuration or startup output.

Choose where the Localtonet client will run

For this workflow, the simplest placement is usually the host that runs Docker. A client on the host can connect to a loopback-published port such as 127.0.0.1:3000. The application container can disappear and return without terminating the host-side Localtonet process.

A persistent management container is another possible architecture, but it changes the target address and Docker networking model. It also introduces its own storage, restart, token-handling, and network-reachability requirements. This guide does not invent a container image, token environment variable, or startup command for the Localtonet client. Use the current supported Localtonet installation workflow for your operating system, and keep the device credential outside the application image.

Choose a fixed host port deliberately

Avoid dynamic port publishing when the tunnel needs a repeatable target. Docker can automatically assign an available host port, but that assigned value may change when the container is recreated. An explicit host mapping makes the target predictable.

Also check that another process is not already using the chosen host port. If Docker cannot bind the port, the container may fail to start or may start without the mapping you expected. The exact port-inspection command varies by operating system, so Docker's own status output and the direct HTTP test should be treated as the authoritative checks for this workflow.

Publish the development server on a stable host port

Two settings must agree:

1. The application must listen on a container interface reachable through the container's network namespace.
2. Docker must publish that container port on the fixed host address and port targeted by the Localtonet tunnel.

A frequent mistake is to publish the correct container port while the development server listens only on 127.0.0.1 inside the container. Inside a container, that loopback address belongs to the container itself. Docker's published-port forwarding generally needs the application to listen on an appropriate container interface, commonly 0.0.0.0. The exact framework option, command-line flag, or environment variable used to select that interface is project-specific. Consult the application's configuration rather than guessing a setting.

Docker Compose port mapping

The following fragment demonstrates the host-to-container mapping. Merge the ports entry into the actual application service in your Compose file. The service still needs its real image or build configuration, startup command, volumes, and any project-specific environment.

services:
  app:
    ports:
      - "127.0.0.1:3000:3000"

The first address and port belong to the host. The final port belongs to the container. With this example, a host process reaches the application at http://127.0.0.1:3000, while the development server listens on port 3000

Binding the published port to 127.0.0.1 limits direct access to processes on the host. This is often a sensible development default when the Localtonet client runs on the same machine. Publishing on every host interface can make the service reachable from the local network, depending on the host firewall and network configuration. Use a broader bind only when the architecture actually requires it.

Direct Docker port mapping

If you run the application without Compose, the equivalent publishing pattern is:

docker run --rm -p 127.0.0.1:3000:3000 your-image

Replace your-image and both ports as required. This command does not configure the process inside the image. The image must still start the intended development server, and that server must listen on the container-side port and an appropriate interface.

Do not target a changing container address

Avoid copying an address from container inspection output into the Localtonet tunnel configuration. That creates a dependency on one container instance. A rebuild can replace the container and assign a different address even when the service name and published host port remain unchanged.

Docker service names are useful for communication between containers on the same user-defined network, but a Localtonet client running directly on the host does not normally resolve a Compose service name through Docker's internal DNS. The published host port is the intentional boundary between the host process and the application container.

Start and inspect the application stack

For a Compose-based project, start the services using the project's existing Compose configuration:

docker compose up -d
docker compose ps
docker compose logs --tail=100 app

Replace app with the real Compose service name. The status output should show the service running and the expected published-port mapping. The logs should show the application's successful startup and the address on which it is listening. If the project intentionally runs in the foreground, omit -d and observe the output directly.

Do not assume that a running container means a working application. A container can remain active while the application reports startup errors, waits for another dependency, or listens on a different port. Continue with direct HTTP verification before configuring Localtonet.

Verify the local target before creating the tunnel

A tunnel cannot repair a broken local route. The most efficient diagnostic method is to prove each boundary in order, beginning as close to the application as practical.

For the example target, a verbose request is:

curl -v http://127.0.0.1:3000/

On systems where the shell maps curl to another command, invoke the installed HTTP client explicitly. The important result is not merely an HTTP status code. Inspect the connection destination, response headers, redirects, and body. A redirect to an internal-only hostname, an unexpected port, or plain HTTP can later affect browser behavior through a public HTTPS address.

Interpret common local outcomes

• Connection refused: no process is accepting traffic at that address and port, or the port is not published as expected.
• Connection timeout: the path may be filtered, routed incorrectly, or directed to an address that is not locally reachable.
• Empty reply or reset: the application may accept the connection and then exit, reject the request, or expect a different protocol.
• 404 response: connectivity works, but the requested path may not exist.
• Host not allowed: the framework is validating the request host. Configure the public hostname through the framework's documented allowlist rather than disabling validation globally.
• Redirect loop: the application may not be interpreting the external scheme or host as intended. Review its trusted-proxy and canonical-URL configuration.

Do not proceed to tunnel troubleshooting until the host-side request succeeds consistently. If the Localtonet client runs on a different device, repeat the test from that device using an address that is reachable from it. A loopback address such as 127.0.0.1 always refers to the device making the connection, not to another computer.

Configure the Localtonet HTTP tunnel

Once the application works through the stable host target, create or update an HTTP tunnel using the documented Localtonet workflow. HTTP and HTTPS application traffic belongs in an HTTP tunnel. Raw TCP and UDP tunnel types solve different forwarding needs and should not be selected merely because a web application uses a TCP connection underneath HTTP.

The central operational rule is straightforward: restart the application container, not the tunnel configuration. Keep the Localtonet client connected and leave the existing tunnel running when you want the public address to remain available for the replacement application process.

Exact custom-domain DNS instructions are not included here because they must be checked against the current Localtonet documentation and the domain configuration shown in the dashboard. Do not guess DNS record types or values. If endpoint continuity is important, validate the selected process type and address behavior before distributing the URL to reviewers.

Prove that the public path survives a container replacement

Do not wait for an important demonstration to discover whether the architecture works. Perform a controlled restart test while monitoring the local application, the Localtonet client, and the browser.

Expected behavior during the restart window

Reviewers may see a temporary browser error, failed fetch, gateway-style error, or stalled request while the application is absent. The exact response is not a reliable indicator of which layer failed. First check whether the host target has returned. Once it does, reload the existing public URL before changing any tunnel settings.

If the host URL returns but the public URL does not, check the Localtonet client connection and tunnel state. If both URLs fail, remain focused on the application and Docker layers. Recreating the tunnel when the host target is broken only adds another changing variable.

Understand WebSockets and hot module replacement

A page can load successfully while hot module replacement, live reload, or another real-time feature remains disconnected. These functions often use a long-lived WebSocket connection that is separate from the initial HTML, JavaScript, stylesheet, and API requests.

A WebSocket session begins as an HTTP request and asks to upgrade the connection. The browser then keeps that connection open so the development server can notify it when files change. Through a public HTTPS page, the browser generally needs a secure WebSocket URL using wss://. A client that attempts an insecure ws:// connection from an HTTPS page can be blocked as mixed content.

Frameworks generate the HMR client configuration in different ways. Some derive the WebSocket host, scheme, and port from the page URL. Others use development-server settings, environment variables, a hardcoded local address, or information injected into the client bundle. There is no universal HMR variable that can safely be recommended for every framework.

Inspect the browser instead of guessing

Open the browser's developer tools and examine both the Console and Network panels. Filter the Network panel for WebSocket connections, commonly shown under a WS filter. Then answer these questions:

• Does the browser attempt a WebSocket connection at all?
• Is the URL using wss:// when the page itself uses public HTTPS?
• Does the WebSocket hostname match the public hostname, or does it incorrectly point to localhost, a container service name, or a private address?
• Does the URL contain the intended public port, or an internal development port that remote browsers cannot reach?
• Does the handshake return an HTTP error, close immediately, or remain connected?
• Does saving a source file produce a message on the connection?

A remote browser interprets localhost as its own device. If the HMR client tries to connect to ws://localhost:3000, it is not connecting back through the public Localtonet address. Configure the development server using its documented public host, client WebSocket, origin, or reverse-proxy settings. The exact option names must come from that framework's current documentation.

Separate page delivery from HMR delivery

Host validation is not the same as CORS

Development servers often validate the HTTP Host value to reduce exposure to hostile hostnames. APIs may separately enforce Cross-Origin Resource Sharing rules, and WebSocket servers may check the Origin header during the handshake. These controls solve related but distinct problems.

If the framework rejects the public hostname, add that exact hostname through its documented configuration. Avoid broad settings that accept every host or origin unless the project documentation explicitly requires them and the risk is understood. A temporary preview is still a public service.

Proxy headers and external URL detection

Applications behind an HTTPS tunnel may need to distinguish the browser-facing public scheme and hostname from the local HTTP connection accepted by the development server. Frameworks sometimes use forwarded headers when generating redirects, absolute links, callback URLs, cookies, or WebSocket endpoints.

The exact headers supplied by Localtonet are not established in the evidence available for this article, so this guide does not claim a specific header set or order. Inspect the request information received by your application and consult the current framework and Localtonet documentation before depending on a particular forwarded header.

Do not enable unrestricted trust for forwarded headers as a reflex. Many frameworks require an explicit trusted-proxy configuration because accepting spoofable forwarding data from arbitrary clients can affect URL generation and security decisions. Trust only the path appropriate for the deployment, using the framework's documented mechanism.

File watching can fail even when WebSockets work

Hot reload has at least two independent sides. The server must detect a file change, and the browser must receive the resulting notification. Bind-mounted files, host filesystem behavior, editor save strategies, and framework watchers can affect the first side. The public tunnel is not involved if the development server never detects the change.

Test HMR locally through the host URL first. If a local browser does not update, troubleshoot file watching and the development server. If local HMR works but public HMR does not, compare the local and public WebSocket requests, focusing on hostname, scheme, port, path, host validation, and origin handling.

Use a strict troubleshooting sequence

Troubleshooting is fastest when each test has one purpose. Changing the container mapping, application bind address, Localtonet target, public hostname, and framework proxy settings at the same time makes the result difficult to interpret.

1. Confirm the application process

Read the current container logs. Confirm that the process remains running, has completed startup, and reports the expected internal port. Look for compilation errors, missing dependencies, occupied ports, failed database connections, and restart loops.

2. Confirm the application bind address

If the server listens only on container loopback, published traffic may not reach it. Configure the server through the project's supported method to listen on an interface reachable through the container. Do not copy a framework-specific flag from another project without verifying that it applies.

3. Confirm the published-port mapping

Run:

docker compose ps

Verify both sides of the mapping. A common mistake is to publish host port 3000 to container port 3001 while the application actually listens on 3000, or to change the Compose file without recreating the container.

4. Test the exact Localtonet target locally

curl -v http://127.0.0.1:3000/

Use the actual target configured for the tunnel. If this request fails on the device running the Localtonet client, stop troubleshooting the public URL. Repair the local route first.

5. Confirm the selected Localtonet device is connected

The client establishes an outbound connection to a Localtonet relay server. No inbound router port forwarding, public IP address, VPN setup, or firewall change is required for the standard tunnel workflow. However, the client still needs working outbound connectivity and must remain connected.

6. Confirm that the existing tunnel is running

A configured tunnel is not automatically active. Check its current state and use Start when necessary. Also confirm that the tunnel references the intended device, relay selection, local IP address, and local port.

7. Test ordinary HTTP before real-time behavior

Open the public root page and a known application route. If normal HTTP fails, WebSocket testing is premature. If HTTP works, proceed to the browser's WebSocket inspection.

8. Inspect browser failures precisely

Record the failing request URL, scheme, hostname, port, status, response, and console message. Statements such as “HMR is broken” hide the distinction between a missing connection attempt, an invalid public URL, a rejected handshake, and a connected socket receiving no messages.

9. Review application host and origin policy

Configure only the public hostname and origins the application needs. If the application has separate controls for ordinary hosts, CORS, WebSocket origins, and callback URLs, review each relevant control instead of disabling all validation.

10. Retest after a clean container replacement

Once the configuration is correct, recreate the container and repeat the local and public tests. This proves that the solution does not depend on a stale container address, manually assigned ephemeral port, or one-time process state.

Expose development previews safely

A public preview is still public infrastructure, even when it is temporary. The absence of router port forwarding does not make the application private. Localtonet lets the client establish an outbound connection and provides a public URL, but application access controls remain important.

• Do not expose environment files, secret-management interfaces, database consoles, debug dashboards, or administrative routes.
• Use application authentication when the preview contains non-public data or privileged actions.
• Create test accounts with limited permissions rather than sharing production credentials.
• Use synthetic or sanitized data whenever possible.
• Review file upload, webhook, form submission, and account-creation behavior before sharing the URL.
• Restrict accepted hosts and origins to the values the preview actually needs.
• Keep authentication tokens out of Compose files committed to source control.
• Stop the tunnel when the review session ends, and delete it when the configuration is no longer needed.

Least privilege should apply to both the application and its surrounding services. A development server that can reach internal databases, cloud metadata services, local files, or privileged Docker interfaces deserves additional caution. Expose only the service intended for review, not a broad network path.

Operational checklist before sharing the link

• The application works at the exact host-side target.
• The container uses an explicit host-port mapping.
• The tunnel points to the host mapping rather than a container IP.
• The Localtonet client runs independently of the disposable application container.
• The selected device is connected and the tunnel is running.
• The public page, static assets, API calls, and authentication flow have been tested.
• Any required WebSocket connection uses the correct public scheme, host, port, and path.
• Host and origin validation permit only the intended values.
• The application contains no secrets or unsafe debug functionality.
• A container restart and a full recreation have both been tested against the same public URL.

Frequently asked questions