Evaluate a Localtonet tunnel companion without inventing unsupported container commands
Running a tunnel client beside a development application can separate public connectivity from application code and make the intended topology easier to review. However, the verified product information available for this guide does not establish an official Localtonet container image, supported container installation path, noninteractive authentication method, startup invocation, hostname-based target rule, or automatic tunnel provisioning interface. This article is therefore an architecture and feasibility guide, not a copy-and-run Docker Compose or Dev Container implementation. It explains the prerequisites, network model, documented HTTP tunnel workflow, validation sequence, lifecycle boundaries, security controls, and product details that must be confirmed before a Localtonet companion service can be approved.
📋 What's in this guide
Support status and the boundary of this guide
The proposed design has two roles. A development application runs in one container and listens for HTTP requests. A companion service would run our client, establish an outbound connection to a Localtonet relay server, and forward public traffic to the application over a route available from the client runtime.
Localtonet is a multi-protocol tunneling and proxy platform. Our client runs on a device that can reach the target service and establishes an outbound connection to a Localtonet relay. A configured and running tunnel provides a public URL or public host and port without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel remains available only while the selected client is connected and the tunnel is running.
Those verified platform properties make a container companion architecture technically plausible. They do not establish that an arbitrary container deployment is supported. A real implementation needs more than an executable in a second service. The client must install successfully in the selected image, authenticate without exposing its device token, remain running under the container lifecycle, reach the application target, and interact predictably with Localtonet tunnel state after restarts and rebuilds.
The verified Localtonet information available for this revision does not identify an official container image, an installation command for an arbitrary Linux container base, a noninteractive client startup command, a documented authentication environment variable, a target-hostname rule, or a supported command or API payload that automatically creates and starts a tunnel. We therefore do not publish a Dockerfile, Compose service, devcontainer.json, image tag, secret variable, startup invocation, or automated tunnel lifecycle. Syntax from another tunnel product must not be adapted and presented as Localtonet behavior.
Before approving an implementation, confirm all of the following against the current Localtonet client release, dashboard, and first-party documentation:
- Whether the Localtonet client is supported inside the chosen container environment.
- Which operating-system distributions and processor architectures are supported.
- The supported package, image, or installation procedure for that environment.
- The documented client startup and noninteractive authentication behavior.
- How a device-specific token can be delivered without placing it in an image layer, repository, process argument, build log, or application configuration.
- Whether an HTTP tunnel target can use a Compose service name or must use a literal IP address.
- Whether an existing device identity can be retained safely when a container is recreated.
- Whether reconnecting a client changes tunnel state or whether the tunnel must still be started independently.
- Whether tunnel creation, start, stop, or deletion can be automated through a currently documented interface.
- How the selected public address behaves after a Dev Container or Compose project rebuild.
Until those questions have verified answers, use this guide to review the topology and build a test plan. The design can still define the network boundary, application listener, credential policy, lifecycle expectations, validation sequence, and shutdown procedure without pretending that unresolved product interfaces already exist.
What the companion-service architecture changes
The application container owns the web server, API, callback handler, webhook receiver, or other preview endpoint. The proposed companion owns the Localtonet client process and its outbound relay connection. Public traffic would travel from the Localtonet relay to the client and then across the local container network to the application listener.
This separation keeps tunnel management out of application code. The application does not need to create tunnels or hold a Localtonet device token. The companion does not need the application source code merely to forward traffic. If the application needs to generate external callbacks, redirects, or absolute links, it may still need to know its public origin, but that is an application configuration concern rather than a reason to merge both processes.
Compose companion service versus Kubernetes sidecar
The word sidecar is often used informally for any helper container, but Docker Compose and Kubernetes use different network and lifecycle models. A Compose companion normally runs as a separate container with its own network namespace. Containers attached to the same Compose network can communicate through the network, and Compose provides service discovery for services on that network. Docker documents this behavior in its Compose networking guidance.
Containers in the same Kubernetes Pod normally share the Pod's network namespace and can communicate over localhost. Kubernetes describes this in its Pod networking documentation. Kubernetes also defines native sidecar containers as a distinct lifecycle pattern in its sidecar container documentation.
These primary-source networking rules explain the general container behavior. They do not establish Localtonet support for either deployment model. Client installation, authentication, target-address handling, and tunnel lifecycle still require current Localtonet confirmation.
| Deployment relationship | Network implication | Design consequence |
|---|---|---|
| Application and client in one host network context | Loopback may refer to a shared operating-system network namespace. | A loopback target can work only if both processes truly share that namespace and the application listens on the expected port. |
| Separate Docker Compose services | Each container normally has its own loopback interface. | The companion cannot reach the application through its own 127.0.0.1. It needs a route across a shared container network or through a deliberately published host port. |
| Containers in the same Kubernetes Pod | Containers normally share the Pod network namespace. | Loopback can represent the shared Pod network, but Localtonet support and the installation method still require confirmation. |
| Localtonet client on the container host | The client reaches a host-published application port. | This avoids installing the client in a container, but the application port must be published deliberately and protected appropriately. |
| Localtonet client on another supported device | The device needs a route to the application target. | The design must account for LAN routing, listener scope, firewall policy, and the security of the local path. |
An architecture diagram that labels the target only as localhost can hide a broken route. Always identify whose loopback interface is meant and test from the exact runtime where our client will execute.
Prerequisites and decisions to make first
Start with an inventory rather than a public URL. Record the application process, listener interface, internal port, Localtonet client location, intended audience, and expected lifetime of the preview. First prove that the proposed client runtime can reach the private application endpoint. Public tunnel configuration comes after that local path works.
Application prerequisites
The development server must listen on an interface reachable from the client. If the application and client are separate Compose services, an application bound only to its own loopback interface will generally not accept traffic arriving through the container network. Many frameworks can listen on an all-interface address such as 0.0.0.0, but the exact option is framework-specific and should come from that framework's documentation.
Listening on all container interfaces is not the same action as publishing a port on the host. Network attachment, listener scope, and host port publication are separate controls. An application can listen on a container-reachable interface while remaining available only to containers on an attached private network. Confirm the result in the actual runtime rather than assuming a particular Compose configuration has the intended boundary.
The internal application port must also be known. This guide does not assign a default because frameworks vary and projects frequently override their defaults. Use the port reported by the running application and verify it from the same network context in which the Localtonet client will run.
Localtonet prerequisites
The normal Localtonet workflow requires a client on a device that can reach the target, a device-specific authentication token, an available relay server or region selected from the current product, and an HTTP tunnel that points to the local application IP address and port. Creating a tunnel does not mean it is running. It must be started and can later be stopped or deleted.
Available relay servers and regions must come from the current dashboard. Do not hardcode a server code from an old example. Device tokens must not be guessed, published, or copied into tutorial configuration.
Application behavior at a public origin
A development application that works at a loopback URL may behave differently behind a public HTTPS address. Review how the framework handles host validation, origin checks, redirects, secure cookies, proxy headers, callback URLs, absolute asset URLs, and persistent development connections. The correct settings come from the framework's current documentation, not from Localtonet.
Decide whether the preview will be unrestricted or protected by application authentication. Development servers often include diagnostics, test records, permissive cookies, source maps, or administrative helpers that should not be exposed to an unknown audience.
A reusable public address, where supported by the selected process type and configuration, does not guarantee that the preview remains available. The selected Localtonet client must be connected, the tunnel must be running, the local route must work, and the development application must be ready.
Design the container network before the tunnel
The most important local test is not whether the application responds inside its own container. It is whether the application responds from the environment where the Localtonet client will run. A development server can pass a self-test over its own loopback interface and still be unreachable from a neighboring container.
Why localhost commonly fails
In separate Compose services, 127.0.0.1 inside the proposed companion refers to the companion itself. It does not refer to the application service. If the companion targets its own loopback address and no application is listening there, the Localtonet client could be connected while requests still fail at the final local hop.
The target therefore needs to resolve or route to the application from the client runtime. Compose commonly provides service discovery for containers on a shared network. However, the verified Localtonet information for this article does not establish that the HTTP tunnel target field accepts a Compose DNS name such as app. General Docker DNS behavior does not prove that a specific Localtonet target field accepts a hostname.
A literal container IP address may appear to solve the problem, but container addresses can change when services or networks are recreated. If the current Localtonet configuration requires a literal IP address, the architecture needs a supported and repeatable way to provide a stable reachable target. This must be resolved before describing the design as rebuild-resistant.
Listener scope and network membership
The application must accept connections on the interface used by the container network. A loopback-only listener is private to its own namespace. An all-interface listener is often useful inside an isolated development network, but it broadens reachability within every network attached to the container. Attach only necessary networks and avoid publishing the application port to the host unless the chosen architecture requires it.
Publishing an application port on every host interface may make a test pass while creating unintended LAN exposure. Prefer the narrowest path that lets the Localtonet client reach the application. If host publication is necessary, choose the bind address and firewall policy according to the development environment's security requirements.
Readiness is different from startup order
Starting the application container before the proposed companion does not prove that the application is ready. Development servers may install dependencies, compile assets, run migrations, or wait for another service before opening their listener. A tunnel can therefore be running while its local target is still unavailable.
Define a harmless readiness check for the application. If the project provides a health endpoint, verify that it does not reveal sensitive diagnostics. Otherwise, use a lightweight application route that proves the server is ready without changing data. A container dependency or restart policy can influence process order, but it cannot prove Localtonet authentication, client connectivity, tunnel execution, or external delivery.
Apply the documented Localtonet HTTP tunnel workflow
Begin the Localtonet portion only after the local route has been proven. The following sequence follows our documented product workflow while keeping unresolved container details outside the instructions. It does not assume an image, environment variable, client command, hostname target, or automation interface.
Install and run the Localtonet client in a supported environment
Run the client on the device or runtime that can reach the development application. For a container companion, first confirm that the current client supports the selected container environment and installation path. If that cannot be confirmed, use a supported host or another supported device with a valid route to the application.
Authenticate or select the intended device
Use the device-specific authentication token through a currently documented method. The token identifies the client device and must not be guessed, committed to source control, embedded in an image, printed in logs, or included in screenshots. A container-safe noninteractive delivery method must be confirmed before this action is automated.
Select an available relay server or region
Select from the values currently offered by our product or dashboard. Available choices can vary, so do not hardcode an unverified server code in project configuration or documentation.
Create the HTTP tunnel for the proven local target
Configure an HTTP tunnel that points to the application IP address and port reachable from the selected client. HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, all of which serve the target content at a public HTTPS address. Confirm current availability and any custom-domain requirements before choosing an option.
Start the tunnel and use the assigned public address
Creating the tunnel does not start it. Use the supported Start action, then confirm that the selected client is connected and the tunnel is running. Record the public HTTPS address and test it only after the local target has already passed the reachability check.
Stop or delete the tunnel when it is no longer needed
Stop the tunnel to end its running public route. Delete it when the configuration should no longer exist. Container shutdown and tunnel shutdown must be treated as separate actions unless a currently documented automation interface explicitly links them.
Consult the current Localtonet HTTP tunnel documentation during implementation for the latest supported fields and interface. The documentation supplements the network and lifecycle testing in this guide. It should not be replaced with guessed Compose settings.
Choose the public address type deliberately
Random Sub Domain, Custom Sub Domain, and Custom Domain process types serve the same application content at a public HTTPS address. Their practical difference is endpoint naming and ownership rather than a different local application target. Exact availability may vary, and custom-domain DNS requirements must be checked against current documentation before configuration is automated.
A generated address may be sufficient for a short manual review. A selected or custom address can be useful when an identity provider, webhook sender, or application allowlist expects a predictable callback. Address predictability still does not guarantee availability. The client must remain connected and the tunnel must remain running.
Validate the preview one layer at a time
Testing only the public URL makes failures difficult to classify. Start at the application and move outward. Record the result at each layer before continuing so that a failed public request does not immediately become an unstructured investigation of every component.
Verify the application in its own runtime
Confirm that the development process has completed startup and responds on the intended internal port. Use a harmless route. Success proves that the application works locally, but it does not prove that another container can reach it.
Verify reachability from the proposed client runtime
Test the same target from the companion container, host, or other supported device where the Localtonet client will execute. This checks listener scope, address resolution, routing, network membership, and port selection.
Verify Localtonet client connectivity
Confirm that the intended device is connected. A disconnected client cannot carry traffic even when the tunnel configuration and public address still exist.
Verify that the HTTP tunnel is running
Confirm that the tunnel has been started and has the expected status. Recheck its configured local IP address and port against the target proven in the previous network test.
Test the public address externally
Open the assigned HTTPS address from a device that is not relying on the same local development route. Verify status, content, redirects, assets, forms, API calls, cookies, and authentication behavior relevant to the preview.
Test long-lived development behavior
If the framework uses WebSockets or another persistent connection for hot reload, inspect the browser connection and trigger an actual source change. Verify that the update arrives and remains usable after an application restart.
WebSocket and hot-reload behavior needs an end-to-end test
Many development servers load the initial page over HTTP and then establish a persistent browser connection for rebuild notifications. A preview can display HTML successfully while automatic reload remains broken. The verified product information supplied for this article does not establish WebSocket behavior, timeout values, or configuration controls for this exact container workflow, so persistent connections are an acceptance test rather than an assumed feature.
If the connection fails, inspect its public URL, scheme, host, status, and origin. Check the framework's host validation, public development-server settings, and generated WebSocket address. Do not disable all host or origin protections to make hot reload work. Add only the exact public host or origin required by the temporary preview.
Check public host and origin handling
Once the application is reached through a public HTTPS address, the browser-visible host and scheme differ from a direct local request. A development server may reject the host, redirect to a private address, generate an insecure browser connection, or reject an unapproved origin.
Configure those controls using the framework's documented settings. Prefer a narrow allowlist for the intended preview origin. Blanket accept-any-host and accept-any-origin settings are risky for a publicly reachable development server and can conceal incorrect public URL generation.
Plan for restarts, rebuilds, and shutdown
Restart-aware design does not mean every component restarts automatically or that the preview has uninterrupted availability. It means the team understands which identities and states survive each event, how a failure is detected, and which recovery actions are supported.
| Event | Effect to evaluate | Required check |
|---|---|---|
| Application process restart | The tunnel may remain running while its local target is temporarily unavailable. | Confirm that the application reopens the same listener and that public requests recover after application readiness returns. |
| Application container recreation | The container address can change and the service may join a recreated network. | Confirm that the configured target remains valid and that the client runtime can reach the replacement container. |
| Proposed companion restart | The selected Localtonet client becomes disconnected during the restart. | Confirm documented authentication, reconnection, and tunnel-start behavior instead of assuming automatic recovery. |
| Full Compose project shutdown | Both containers stop, while the tunnel configuration may continue to exist in the dashboard. | Stop the tunnel deliberately and confirm its state whenever public access must end. |
| Dev Container rebuild | Containers, writable layers, networks, and unpersisted identity data may be replaced. | Confirm whether client identity can be retained safely and whether the existing tunnel can be associated with the recreated runtime. |
| Tunnel stop or deletion | The public route becomes unavailable even if the application and client remain healthy. | Distinguish an intentional tunnel action from an application, client, or local network failure. |
Restart policies do not prove readiness
A container restart policy can relaunch a failed process. It cannot prove that Localtonet authentication succeeded, the intended device identity is active, the target is reachable, the tunnel is running, or the public address is unchanged. Those outcomes require documented product behavior and direct testing.
Avoid a restart loop that repeatedly submits invalid credentials or retries an unreachable target. Until the exact client behavior is confirmed for the selected environment, test restarts in a disposable development environment and record what happens to client identity, tunnel status, target reachability, and the public address.
Use a deliberate operational checklist
At the start of a preview session, verify the application, local route, client connection, tunnel state, and public response in that order. During the session, treat an unavailable preview as a layered state problem rather than immediately recreating the tunnel. Recreating resources can hide the original fault and may produce additional endpoint or identity changes.
When the review is complete, stop the public tunnel first if immediate access revocation matters. Then stop the Localtonet client and application services. Delete the tunnel if it should not be reused. Remove or rotate any development-only secret according to the team's policy.
Stopping the application before the tunnel changes a working preview into an unavailable backend, but it does not by itself establish that the tunnel was stopped or deleted. Likewise, deleting a container does not prove that its device credential was revoked or its tunnel record was removed.
Localtonet platform-wide Token/Tunnel webhooks can report Connected or Disconnected changes for a token or tunnel in a selected Token Group. They send a WebHookRequest containing Id, ActionDate, Type, and Status. Receiving a status notification is not the same as automatically starting or stopping a tunnel. These platform webhooks are also separate from File Server webhooks, which report file-level events such as upload, delete, rename, and move.
Protect credentials and limit preview exposure
Development applications can contain debugging pages, test data, source maps, permissive cookies, incomplete authorization, or administrative helpers that were never intended for public use. A tunnel changes reachability, not the application's security posture. Review the service as internet-reachable before starting the tunnel.
Keep the device token out of build artifacts
A Localtonet authentication token identifies a client device. It must not be copied into a Dockerfile, image layer, committed Compose file, application settings file, shell history, issue tracker, browser bundle, screenshot, or example log. Removing the value from a later commit does not remove it from earlier version-control history or image layers.
The verified information available here does not define a supported Localtonet environment variable or secret-file interface for container authentication. Do not create a plausible-sounding variable name. First identify the documented client authentication mechanism, then choose a runtime secret-delivery method compatible with that mechanism and the team's container platform.
Apply least exposure
- Expose only the application port required for the preview.
- Do not attach the application or companion to unrelated container networks.
- Avoid publishing the application port to the host unless the design requires it.
- Keep production credentials and production data out of development previews.
- Require application authentication when the content is not intended for unrestricted public viewing.
- Use narrow host and origin allowlists instead of disabling validation globally.
- Review callback, redirect, and cookie settings for the exact public HTTPS origin.
- Stop or delete the tunnel promptly when the review session ends.
- Keep device tokens, private endpoints, and credentials out of support bundles and troubleshooting reports.
The absence of inbound router port forwarding does not make the application private. Anyone who can reach the public endpoint can attempt to access it unless the application or another verified control requires authorization. Do not expose an unauthenticated administrative console, development database browser, debugger, or secret-bearing diagnostics page.
Troubleshoot by following the traffic path
The application works in its own container but not from the client runtime
Treat this as a local networking problem. Confirm that the application listens on a container-reachable interface, the relevant services share the intended network, the target port is correct, and the chosen address resolves from the client runtime. In separate Compose services, the companion's localhost is not the application container.
The client is connected but the public address fails
Client connectivity and tunnel execution are separate states. Confirm that the HTTP tunnel has been started. Then compare its local IP address and port with the target already proven reachable from the client runtime. If the target uses a container service name, confirm that the current Localtonet target field supports that hostname format.
The endpoint exists but appears offline
A saved tunnel configuration does not imply availability. Verify the selected client connection, tunnel state, local route, and application readiness independently. Endpoint identity, client connectivity, tunnel execution, network reachability, and backend health are distinct conditions.
The page opens but assets or API calls fail
Inspect browser requests for loopback addresses, private hostnames, incorrect schemes, blocked origins, and redirects. Applications sometimes generate absolute URLs from their local configuration. Use the framework's documented public-origin, proxy, host, and origin settings rather than replacing all validation with permissive defaults.
The page loads but hot reload does not work
Locate the browser's persistent development connection and inspect its URL, scheme, status, and origin. It may point to a private hostname, use an insecure scheme from an HTTPS page, or fail the framework's origin check. Trigger a real source edit and observe the result. Do not infer persistent-connection behavior from a successful initial page load.
The application rejects the public hostname
Add the exact preview host or origin through the application's documented allowlist mechanism. Avoid disabling host validation for all requests. If a custom domain is involved, follow current Localtonet domain and DNS instructions rather than guessing record types or propagation behavior.
The preview stops after a rebuild
Determine whether the application target changed, the client runtime lost its device identity, authentication was unavailable, the client remained disconnected, or the tunnel remained stopped. Test each layer separately. Do not solve the failure by embedding a token in an image or creating a new tunnel on every startup without a documented lifecycle.
A changing container IP breaks the target
This indicates that the design depends on an unstable local address. Confirm whether the current HTTP target accepts a Compose-resolvable service name. If it does not, redesign around a supported stable target, run the client in another supported network context, or use only a documented method of updating the tunnel. Do not invent a Localtonet command or REST payload.
Compose shutdown leaves uncertainty about exposure
Check the tunnel state directly. Container shutdown, client disconnection, tunnel stopping, and tunnel deletion are separate events. If public access must end, stop the tunnel deliberately and confirm the resulting status rather than relying on an inferred side effect of Compose shutdown.
Frequently asked questions
Is this a runnable Localtonet sidecar tutorial?
No. It is an architecture and feasibility guide. A runnable tutorial would require a verified Localtonet container image or installation path, client startup method, noninteractive authentication mechanism, target-address rule, and supported tunnel automation interface. Those details are not established by the evidence available for this revision.
Is there an official Localtonet Docker image for this design?
An official Localtonet container image is not established by the verified product information available for this guide. We therefore do not provide an image name, tag, Dockerfile, installation command, or Compose service. Confirm current container support before implementing the design.
Can a Localtonet companion target localhost?
Not when localhost belongs to a separate Compose container and the application runs in another container. Each container normally has its own loopback interface. The client needs an address and port that reach the application over an available network route. Containers in the same Kubernetes Pod have a different network model because they normally share the Pod network namespace.
Can an HTTP tunnel target use a Docker Compose service name?
Docker Compose provides service discovery on shared networks, but the verified Localtonet information for this revision does not confirm that the HTTP tunnel target accepts a Docker DNS name such as app. Confirm the accepted target format in the current Localtonet product or documentation before depending on service-name resolution.
Does creating a Localtonet tunnel automatically start it?
No. Creating a tunnel does not mean it is running. It must be started using the supported Start action and can later be stopped or deleted.
Does a stable public URL guarantee that the preview stays online?
No. Public address identity and runtime availability are separate. The selected client must be connected, the tunnel must be running, the local target must be reachable, and the development application must be ready.
Will WebSocket hot reload work through the preview?
Test it for the exact framework and configuration. The evidence available for this guide does not establish specific WebSocket behavior for the proposed container workflow. Verify the persistent browser connection, public scheme, generated host, origin validation, and actual reload behavior after a source change.
Should the development application bind to 0.0.0.0?
In a separate-container design, the application must listen on an interface reachable through the container network rather than only its own loopback interface. Many frameworks use 0.0.0.0 for that purpose, but the exact setting is framework-specific. Restrict network attachments and avoid unnecessary host port publication because a broader listener increases reachability within attached networks.
Where should the Localtonet device token be stored?
Keep it out of source control, image layers, application configuration, browser code, command examples, and logs. Use only a secret-delivery method compatible with the currently documented Localtonet authentication mechanism. This guide does not invent an environment variable or secret-file interface.
Is stopping Docker Compose enough to end public access?
Do not rely on that assumption. Container shutdown, client disconnection, tunnel stopping, and tunnel deletion are separate events. Stop the tunnel deliberately when access must end, delete it if it should not be reused, and confirm the resulting status.
Evaluate your preview architecture with Localtonet
Begin with a supported Localtonet client environment and prove that it can reach the development application. Then create and start an HTTP tunnel through the documented workflow, validate every network layer, protect the device token, and define a deliberate shutdown procedure. Move to a container companion implementation only after its installation, authentication, target-address, and lifecycle requirements are confirmed.
Get Started Free →
