Keep a Tunnel URL Stable Across Container Restarts

Separate the tunnel lifecycle from the container lifecycle

A repeatable development preview begins with a lifecycle decision. The Localtonet client and the application container should not share the same disposable lifecycle. Development containers are routinely restarted, rebuilt, or recreated after source, dependency, image, or configuration changes. If the tunnel client runs inside that same container, replacing the application also terminates the client and complicates device identity, credentials, tunnel state, and reconnection behavior.

For the pattern in this guide, run the Localtonet client on the host operating system or on another persistent device that can reliably reach the application. The development server listens inside its container, Docker publishes that server through a predictable host port, and the Localtonet HTTP tunnel uses the host-side address and port as its local target.

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

The objective is to preserve the existing tunnel configuration while replacing only the application behind its fixed target. A container restart or recreation does not inherently require a new Localtonet tunnel. While the container is absent, however, there is no application process behind the host port. Requests can fail until the replacement becomes ready.

Four operations that should not be confused

Stopping a tunnel is also different from restarting the application. Localtonet tunnels are available only while the selected client is connected and the tunnel is running. Because endpoint behavior can depend on the selected process type and current product conditions, this article does not promise that an address will survive every stop-and-start sequence. If continuity matters, keep the existing configuration, avoid unnecessary lifecycle changes, and test the exact process type you plan to distribute.

Why a container IP address is usually the wrong target

Containers commonly receive private addresses from Docker-managed networks. Those addresses belong to container instances and can change when containers are recreated. A host process should not depend on a current container address when Docker can expose the service through a deliberate published port.

If the Localtonet client runs on the Docker host, configure the tunnel to use the published host address and port. The replacement container can receive a new private address while the host-side target remains unchanged.

Independent states determine whether the preview works

Prepare the host, container, and application

Identify and verify the service boundary before creating public access. Start with a predictable local URL, not with the public endpoint.

• A development application that runs in a Docker or compatible development container.
• The actual port used by the application inside the container.
• A fixed and currently unused host port.
• A Docker mapping from the host address and port to the application port.
• The Localtonet client installed and running on the host, or on another persistent device that can reach the selected local target.
• A device-specific Localtonet authentication token selected through the supported client and dashboard workflow.
• An available relay server or region selected from the current Localtonet dashboard.
• A local HTTP client such as curl and browser developer tools for testing.

Examples in this guide use container port 3000 and host target 127.0.0.1:3000. These values demonstrate the architecture only. Use the port shown by your application configuration or startup output.

Choose where the Localtonet client runs

The simplest placement for this pattern is normally the Docker host. A host-based client can target a loopback-published port such as 127.0.0.1:3000. Replacing the application container then has no direct effect on the Localtonet client process.

A separate persistent management container is a different architecture. It introduces container installation support, noninteractive authentication, secret handling, service discovery, storage, and restart questions. Our verified product information does not provide a general Localtonet container image, container startup command, or environment-variable authentication recipe for this use case. Do not invent those details or copy commands from another tunnel product.

If you are evaluating a separate container companion, read our Localtonet Dev Container tunnel companion architecture guide. It explains which support and implementation details must be confirmed before that design becomes a runnable recipe.

Choose a fixed host port

Avoid automatic host-port assignment when a tunnel needs a repeatable local target. Docker can select an available host port, but the selected value can differ after recreation. An explicit mapping makes the boundary predictable.

Check that another process is not already using the selected host port. If Docker cannot bind it, the service may fail to start. Docker status output, container logs, and a direct request to the host URL provide the most useful evidence.

Publish the development server on a fixed host port

Two settings must agree. The application must listen on a container interface reachable through Docker networking, and Docker must publish that container port on the host address targeted by Localtonet.

A frequent mistake is publishing the correct port while the application listens only on 127.0.0.1 inside the container. Container loopback belongs to that container. Published traffic commonly requires the application to listen on an appropriate container interface, often 0.0.0.0. The exact framework flag, configuration key, or environment variable is version-dependent. Use the current documentation for your development server rather than assuming that another framework's setting applies.

Docker explains the underlying behavior in its port-publishing documentation. Published ports can be exposed beyond the host depending on the address used, so select the host bind address deliberately.

Docker Compose port mapping

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

Merge this ports entry into the actual application service. The first address and port belong to the host. The final port belongs to the container. The service still requires its real image or build configuration, startup command, volumes, dependencies, and project-specific environment.

Binding to 127.0.0.1 makes the published port available to processes on the Docker host without deliberately publishing it on every host interface. This is a useful default when the Localtonet client runs on the same machine. If the client runs on another device, that device cannot reach the Docker host's loopback interface. Use an appropriate reachable host address and apply the network controls required by that architecture.

Direct Docker port mapping

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

Replace your-image and both ports as required. Port publishing does not configure the process inside the image. The image must start the intended server, and the server must listen on the selected container port and an interface reachable through the container network.

Do not target the current container address

Avoid copying a private address from container inspection output into the Localtonet tunnel. That couples the tunnel to one container instance. A rebuild can replace that instance and assign another address even though the service still publishes the same host port.

Docker service names are useful between containers attached to the same user-defined network. A Localtonet client running directly on the host does not normally use Docker's internal service-name resolution. The published host port is the intended boundary for this design.

Start and inspect the Compose stack

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

Replace app with the actual service name. The status output should show the expected port mapping, and the logs should show successful application startup. If the project intentionally runs in the foreground, omit -d.

A running container does not necessarily contain a working application. The application may be waiting for a dependency, reporting compilation errors, or listening on a different port. Verify the host URL before configuring Localtonet.

Verify the local target before creating the tunnel

A public tunnel cannot repair a broken local route. Prove each local boundary first.

curl -v http://127.0.0.1:3000/

Inspect the connection destination, status, headers, redirects, and response body. A redirect to an internal hostname, an unexpected port, or an incorrect scheme can later break browser behavior through the public HTTPS endpoint.

Interpret common local outcomes

• Connection refused: no process accepts traffic at the selected address and port, or Docker did not publish the port as expected.
• Connection timeout: the route may be filtered, directed to the wrong address, or unreachable from the client device.
• Empty reply or reset: the application accepted the connection and then rejected it, exited, or expected another protocol.
• 404 response: the network path works, but the requested route may not exist.
• Host rejected: the framework may validate the request hostname. Add the required public hostname through the framework's documented and version-appropriate allowlist.
• Redirect loop: the application may not understand the browser-facing scheme or host. Review canonical URL and trusted-proxy configuration.

Do not troubleshoot the public endpoint until the host-side request works consistently. If the Localtonet client runs on another device, perform the test from that device. The address 127.0.0.1 always refers to the device making the connection.

Configure the Localtonet HTTP tunnel

After the fixed host target works, follow the current Localtonet HTTP tunnel documentation. Use an HTTP tunnel for an HTTP or HTTPS web application. Raw TCP and UDP tunnels serve different forwarding requirements and should not be selected merely because HTTP ultimately runs over TCP.

The documented setup sequence is represented below without adding unsupported fields or commands.

The operational rule is simple: when changing the application, restart or recreate the application container rather than deleting the tunnel. Continue using the existing tunnel configuration and its fixed local target.

Localtonet supports Random Sub Domain, Custom Sub Domain, and Custom Domain process types for HTTP tunnels. Exact custom-domain DNS instructions are not included because they must be checked against the current dashboard and documentation. Do not guess DNS records or values.

Test restart and recreation without replacing the tunnel

Test both a restart and a recreation before an important demonstration. They are not equivalent Docker operations. A restart stops and starts the existing container. A recreation replaces it and is the stronger test of whether you accidentally depended on container identity.

Docker documents Compose restart behavior separately from Compose up and recreation behavior. In particular, a restart does not apply changes made to the Compose configuration. If you changed ports, environment values, image settings, or other service configuration, use the project's appropriate docker compose up workflow so Docker can recreate the service.

Expected behavior during the interruption

A reviewer may see a browser error, failed fetch, gateway-style response, or stalled request while the application is absent. The exact browser symptom does not identify the failed layer. Check the host target first. Once it returns, reload the same public URL before changing the tunnel.

If the host URL works but the public URL does not, inspect the Localtonet client and tunnel state. If both fail, continue troubleshooting the application and Docker layers. Recreating a tunnel while the host target is broken introduces another variable without repairing the local service.

Understand WebSockets, mixed content, and hot module replacement

A page can load while hot module replacement, live reload, or another real-time feature remains disconnected. These features commonly use a WebSocket connection separate from the requests for HTML, JavaScript, stylesheets, and APIs.

A WebSocket connection starts with an HTTP handshake and then upgrades to a persistent bidirectional connection. The WebSockets standard defines browser-facing WebSocket behavior. When a page is delivered over public HTTPS, its browser-facing socket normally needs the secure wss:// scheme. An insecure ws:// request from a secure page can be blocked under browser mixed-content rules.

HMR behavior is framework-specific and version-specific. Some development servers derive the socket hostname, scheme, and port from the page URL. Others use explicit client settings, environment values, reverse-proxy configuration, or data injected into the client bundle. There is no universal HMR option that applies safely to Vite, Next.js, webpack development servers, and every other framework version.

Inspect the browser rather than guessing

Open the Console and Network panels in browser developer tools. Filter for WebSocket traffic and answer these questions:

• Does the browser attempt a WebSocket connection?
• Does it use wss:// when the page is loaded over public HTTPS?
• Does the hostname match the public application hostname?
• Does it incorrectly use localhost, a Docker service name, or a private address?
• Does it use the intended browser-facing port and path?
• Does the handshake return an error, close immediately, or stay connected?
• Does saving a source file cause the server to send an update?

A remote browser interprets localhost as the reviewer's own device. If generated client code attempts to connect to ws://localhost:3000, it is not returning through the Localtonet endpoint. Use the current documentation for the exact framework version to configure its browser-facing HMR host, protocol, port, path, public origin, or reverse-proxy behavior.

Separate page delivery from HMR delivery

Host validation, CORS, and WebSocket origin checks are different

A development server may validate the HTTP Host value. An API may separately enforce Cross-Origin Resource Sharing rules. A WebSocket implementation may inspect the Origin value during its handshake. These mechanisms are related to request acceptance but are not interchangeable.

If the application rejects the public hostname, add the exact required value through its documented, version-appropriate configuration. Avoid disabling host or origin validation globally. A temporary development server is still public while the tunnel is running.

Forwarded headers and trusted proxies

An application behind a public HTTPS endpoint may accept a local HTTP connection while the browser sees HTTPS. Applications sometimes use proxy-provided forwarding information to generate redirects, absolute links, callback URLs, secure cookies, and WebSocket endpoints. The standardized Forwarded HTTP extension describes one such header format, while frameworks may also support other conventions.

This article does not claim which forwarding headers Localtonet supplies or how a particular framework interprets them. Inspect the request information received by your application and consult the current Localtonet and framework documentation before relying on any header.

Do not enable unrestricted proxy trust as a reflex. Frameworks differ in how they determine which proxy hops are trusted, and incorrect trust can allow client-supplied forwarding values to influence scheme detection, host generation, IP-based controls, or security decisions. Configure only the trust relationship required for the verified deployment path.

File watching can fail even when the socket works

HMR has at least two independent sides. The server must detect a changed file and generate an update, and the browser must receive and apply that update. Bind mounts, host filesystem behavior, editor save strategies, polling settings, framework versions, and watcher implementations can affect detection.

Test HMR through the host URL first. If local HMR also fails, investigate file watching and the development server. If local HMR works but public HMR fails, compare the local and public WebSocket requests, including their scheme, host, port, path, origin, response status, and connection lifetime.

Troubleshoot from the application outward

Change one layer at a time. Simultaneously changing the application bind address, Docker mapping, Localtonet target, hostname policy, and proxy settings makes the result difficult to interpret.

1. Confirm the application process

Read the current logs. Confirm that the process remains running, finishes startup, and reports the expected internal port. Resolve compilation failures, missing dependencies, occupied ports, failed backend connections, and restart loops first.

2. Confirm the application bind address

If the development server listens only on container loopback, published traffic may not reach it. Use the project's supported and version-appropriate setting to select a reachable interface.

3. Confirm the published-port mapping

docker compose ps

Verify both sides of the mapping. A common mistake is publishing host port 3000 to container port 3001 while the process actually listens on 3000. Another is editing the Compose file and using only docker compose restart, which does not apply the changed configuration.

4. Test the exact Localtonet target locally

curl -v http://127.0.0.1:3000/

Run the test from the Localtonet client device. If it fails there, repair the local route before changing the tunnel.

5. Confirm that the selected Localtonet client is connected

Our client establishes an outbound connection to a Localtonet relay. The standard tunnel workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes. The client still needs working outbound connectivity and must remain connected.

6. Confirm that the existing tunnel is running

Creating a configuration does not automatically start it. Confirm the tunnel state, use Start when necessary, and verify its selected AuthToken, server, local IP address, and local port.

7. Test ordinary HTTP first

Open the public root page and a known application route. If ordinary HTTP fails, WebSocket testing is premature.

8. Record browser failures precisely

Record the failing URL, scheme, hostname, port, path, status, response, and console message. “HMR is broken” does not distinguish a missing connection attempt from an incorrect URL, rejected handshake, disconnected socket, or absent file-change event.

9. Review host, origin, and proxy policy

Configure only the hosts, origins, callback URLs, and proxy relationships the application needs. Use documentation for the exact framework and version rather than copying a broad allow-all setting.

10. Repeat the test after recreation

Recreate the application container and repeat the local and public checks. This confirms that the design does not depend on a stale private address, automatically allocated host port, or one-time process state.

Expose development previews safely

A public preview is public infrastructure, even when it is temporary. Avoiding router port forwarding does not make the application private. Localtonet provides a public route to the selected service while the client is connected and the tunnel is running. Application authorization and safe configuration remain your responsibility.

• Do not expose environment files, secret-management pages, database consoles, debug dashboards, or administrative routes.
• Use application authentication when a preview contains non-public data or privileged actions.
• Create limited test accounts instead of sharing production credentials.
• Use synthetic or sanitized data where possible.
• Review upload, webhook, form submission, account creation, and destructive-action behavior.
• Restrict accepted hosts and origins to the values the preview needs.
• Keep Localtonet device tokens out of images, repositories, Compose files, logs, and screenshots.
• Stop the tunnel when access is no longer required.
• Delete the tunnel only when the configuration and any continuity associated with it are no longer needed.

Apply least privilege to surrounding services as well. A development server that can reach production databases, cloud metadata endpoints, local secret files, privileged Docker sockets, or administrative networks requires additional isolation. Expose only the intended application service, not a broad network path.

Operational checklist

• 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 private container address.
• The Localtonet client runs independently from the disposable application container.
• The selected device is connected and the existing tunnel is running.
• The public page, assets, API calls, authentication flow, and redirects have been tested.
• Required WebSockets use the intended public scheme, hostname, port, and path.
• Host and origin policies allow only the values the application needs.
• The application contains no exposed secrets or unsafe debug functionality.
• A normal restart and a full recreation have both been tested against the existing public address.
• The current process type and dashboard behavior have been checked before promising a long-lived address.

Frequently asked questions