Make public preview access part of your repeatable container development architecture
A tunnel sidecar places the Localtonet client alongside an application in a Docker Compose based development environment. This pattern separates public connectivity from application code while keeping both services within a reproducible project topology. The key networking detail is that localhost inside the tunnel container refers to that container, not automatically to the application container. This guide explains service-name routing, tunnel lifecycle boundaries, validation scenarios, token handling, and the decisions that must be verified before committing an exact Compose configuration.
What a tunnel sidecar changes
A sidecar is a supporting service that runs next to a primary application without becoming part of the application itself. In this architecture, the application container owns the web server, API, webhook receiver, or other development workload. A separate container runs the Localtonet client and provides the public connectivity layer. The application does not need to contain tunnel management logic, and the tunnel container does not need access to the application source code unless a specific deployment design requires it.
With Localtonet, the client running on the selected device establishes an outbound connection to our relay server. The resulting tunnel provides a public URL or a public host and port, depending on the tunnel family. This does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The public endpoint forwards traffic toward the configured local target that is reachable from the client.
In a Dev Container workflow, the word “device” needs careful interpretation. The Localtonet authentication token identifies the client instance that runs the tunnel. If the client runs inside a container, the container environment must receive the correct device-specific token securely. The token must never be guessed, committed to source control, copied into an image layer, printed in documentation, or exposed in shared logs.
Why localhost usually fails between containers
Each ordinary Docker container has its own network namespace. Inside the application container, an address such as 127.0.0.1:3000 refers to port 3000 in the application container. Inside a separate tunnel container, the same address refers to port 3000 in the tunnel container. It does not automatically cross into the application container.
This distinction causes a common failure mode. The application is healthy when tested from its own terminal, but the sidecar reports that its target is unavailable. Both observations can be correct because they refer to different loopback interfaces. Publishing the application port to the host may make it reachable from the host, but host port publication is not normally required for communication between services attached to the same suitable Compose network.
The more direct model is to configure the tunnel target using the application’s Compose service name and its container port. Conceptually, if the application service is named app and listens on port 3000, the sidecar needs to reach app:3000, not localhost:3000. This is an architectural example rather than a complete Localtonet configuration. Exact container images, installation methods, environment variable names, startup commands, and client invocation details must be checked against current Localtonet documentation before publication or implementation.
Service-name resolution alone is not enough if the application binds only to its own loopback interface. A process listening exclusively on 127.0.0.1 inside the application container may reject traffic arriving through the container network. Configure the development server to listen on an interface reachable from the sidecar, while limiting exposure through network design and application access controls.
Choose the correct Localtonet tunnel family
The sidecar pattern does not change the meaning of our tunnel types. Select the family according to the application protocol rather than according to the fact that Docker is involved. A browser-facing development site or HTTP API generally fits an HTTP/s tunnel. A protocol that needs raw port forwarding may require TCP, UDP, combined UDP/TCP, or TLS behavior. File Server publishes a local folder path and is not a substitute for forwarding a web application.
| Localtonet family | Typical development use | Target behavior |
|---|---|---|
| HTTP/s | Web applications, HTTP APIs, OAuth callbacks, and webhook receivers | Points to a local IP address or resolvable service name and port reachable from the client |
| TCP | Services that require raw TCP forwarding rather than HTTP request handling | Forwards TCP traffic to the configured local target and port |
| UDP | Development services that communicate over UDP | Forwards UDP traffic to the configured local target and port |
| Combined UDP/TCP | Applications that need both transport protocols on the relevant service | Uses a local target reachable from the selected Localtonet client |
| TLS | Services that need the documented TLS tunnel behavior | Points to a reachable local IP address or service name and port |
| File Server | Publishing a development folder through Default, SFTP, or WebDAV modes | Targets a local folder path rather than an application host and port |
HTTP and File Server tunnels may use a generated subdomain, a selected subdomain where supported, or a custom domain. These Process Type choices serve content at a public HTTPS address. Exact custom-domain DNS requirements and endpoint persistence behavior must be confirmed against the current dashboard and documentation before they are added to a container workflow.
Plan the sidecar lifecycle before writing Compose configuration
A reproducible topology is more than two service definitions. The application, Localtonet client, and configured tunnel have related but distinct lifecycles. The application can be running while the client is disconnected. The client can be connected while a tunnel exists but remains stopped. A running tunnel can also fail to reach its local target if the application is still starting, listening on the wrong interface, or attached to a different network.
Dev Container rebuilds make these boundaries especially important. Rebuilding may replace the sidecar container, restart the client process, or recreate the Compose network. The public tunnel is available only while the selected client or device is connected and the tunnel is running. Do not assume that recreating a container preserves a public endpoint, automatically starts an existing tunnel, or creates a new tunnel with identical addressing. Those behaviors must be validated against the current Localtonet client and dashboard before an exact automation design is approved.
Startup dependencies can improve sequencing, but they do not prove application readiness by themselves. A container process may have started before its HTTP listener is ready. A robust design should distinguish process startup, application readiness, Localtonet client connectivity, and tunnel status. The specific Compose health checks and dependency conditions depend on the application image and are not Localtonet dashboard fields.
Documented Localtonet workflow for a sidecar design
Install and run the Localtonet client
The client must run in the environment that can reach the application service. For a true sidecar design, that means installing and running a supported Localtonet client inside the sidecar container. Verify the current operating system installation method before choosing a base image or writing a Dockerfile.
Authenticate or select the sidecar device
Use the device-specific authentication token associated with the client that will run the tunnel. Supply it through an approved secret mechanism outside the repository. Do not place the token in Compose files, Dev Container configuration committed to source control, image layers, screenshots, or example logs.
Select an available relay server or region
Choose from the values currently presented by our product or dashboard. Server codes and regional availability can change and may vary, so do not hardcode an undocumented value based on an old example.
Create the appropriate tunnel configuration
Select HTTP, raw port forwarding, File Server, proxy, or VPN configuration according to the actual use case. For an application sidecar, configure the local target so the Localtonet client can resolve and reach the application service over the Compose network. Do not describe standard HTTP, TCP, or UDP tunneling as VPN functionality.
Start the tunnel and validate the assigned endpoint
Creating the tunnel does not mean it is running. Start it with the Start control, then use the assigned public URL or host and port. Confirm both the client connection and tunnel state before diagnosing application-level failures.
Stop or delete the tunnel when it is no longer needed
Treat shutdown as part of the development workflow. Stop the tunnel when public access is no longer required, or delete it when the configuration should not be retained. Compose teardown and Localtonet tunnel deletion are separate concepts unless verified automation explicitly connects them.
Consult the current Localtonet documentation before translating this workflow into exact Docker instructions. Client installation commands, container compatibility, dashboard labels, automatic startup behavior, and endpoint persistence require current verification and should not be inferred from the architectural pattern alone.
Validate the public preview as a system
Browser and remote preview access
Begin with a simple browser request to the assigned public HTTPS address when using an HTTP tunnel. Confirm that the response comes from the intended development service rather than another container or stale process. Test a distinctive route or version marker so that a cached page does not create a false positive.
OAuth callback testing
An OAuth provider must redirect to the exact callback address registered with that provider. A public preview can make a local callback handler reachable, but the provider’s redirect URI rules, application credentials, cookie settings, and state validation remain application responsibilities. If the public endpoint changes after a rebuild, the registered callback may also need to change. Endpoint persistence must be verified before designing automation around a fixed callback address.
Webhook delivery
A webhook sender can deliver an HTTP request to a public Localtonet URL that routes to the receiver in the application container. Validate method, path, response status, signature checking, and duplicate-delivery handling. File Server file-event webhooks and platform-wide Token/Tunnel webhooks are separate Localtonet systems and should not be confused with an external service calling your development application.
WebSocket connections
A page loading successfully does not prove that a WebSocket connection works. Test the complete upgrade and message flow from a remote browser or client. Check the application’s origin rules, public scheme, generated client configuration, and the address used by frontend code. Do not assume that a browser should connect directly to a private Compose service name, because that name is normally meaningful inside the container network rather than on the public internet.
Expose only the service required for the test. Keep development dashboards, databases, debuggers, administration routes, and unrelated ports private. Apply authentication, least privilege, application authorization, IP restrictions where available and appropriate, secure webhook signature validation, and short tunnel lifetimes. Never use a public tunnel to bypass organizational network policies or required security controls.
Operational review checklist
Before a team adopts this architecture, review who owns the Localtonet device token, how it is injected, and how access is revoked. Decide whether each developer receives an individual device identity or whether another approved model is appropriate. Avoid sharing one token casually across unrelated environments.
Confirm that the sidecar and application join the intended Compose network and that the target uses the application’s service name and container port. Verify that the application listens on a reachable interface. Test behavior when the application starts slowly, crashes, or restarts while the tunnel client remains connected.
Finally, rehearse teardown and rebuild behavior. Observe whether the Localtonet client reconnects, whether the existing tunnel remains stopped or must be started again, and whether the assigned endpoint changes. Record only behavior verified with the current client and plan. Do not turn one local observation into a universal product claim because options can vary by client version, configuration, deployment, or subscription.
Frequently asked questions
Why can the Localtonet sidecar not reach localhost in the application container?
Each ordinary container has its own loopback interface. Localhost inside the sidecar refers to the sidecar itself. Use an appropriate shared Compose network and target the application by its service name and container port.
Does creating a Localtonet tunnel automatically make it available?
No. Creating a tunnel and running it are separate lifecycle states. The selected client must be connected, and the tunnel must be started before the assigned public URL or host and port becomes available.
Does the sidecar require inbound router port forwarding?
No. The Localtonet client establishes an outbound connection to our relay server, so the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Should a device token be stored in docker-compose.yml?
No. A Localtonet token is device-specific authentication material. Keep it out of source control, container images, example configuration, logs, and screenshots. Inject it using an approved secret mechanism suitable for the development environment.
Will a public URL remain the same after rebuilding the Dev Container?
Do not assume that it will. Endpoint behavior can depend on the tunnel configuration, Process Type, current product behavior, and available options. Verify persistence with the current Localtonet dashboard and documentation before relying on a fixed OAuth callback or webhook address.
Is a Localtonet HTTP tunnel the same as a VPN?
No. HTTP, TCP, UDP, TLS, combined UDP/TCP, and File Server tunnels expose specific services or folders. VPN Manager is our actual private mesh VPN feature and should be treated as a separate architecture.
Design your Localtonet development sidecar
Start by mapping the application service name, container port, tunnel family, device identity, and shutdown policy. Then verify the current client installation and dashboard behavior before committing an exact Docker Compose implementation.
Get Started Free →
