Public HTTPS Origins for Multi-Service Monorepos

Why a multi-service monorepo needs an origin architecture

A monorepo is a source-code organization model, not a networking model. Even when the frontend, backend, authentication code, and shared packages live in one repository, the running system can contain several independent listeners. A browser application might load from one local port, call an API on another, redirect through an authentication service on a third, and connect to a WebSocket endpoint used for hot reload or live application events.

On the local machine, developers often hide this complexity behind addresses such as localhost with different ports. Public HTTPS changes the situation. Every browser-visible scheme, hostname, and port contributes to an origin. OAuth providers compare redirect addresses, cookies are sent according to host, domain, path, security, and same-site rules, and WebSocket clients need a reachable public endpoint using the correct scheme. A tunnel can provide connectivity, but it cannot decide which services should share an origin or automatically reconcile application configuration.

The architectural question is therefore not simply, “Which port should we expose?” It is, “What public origin topology should this application present?” There are three common answers:

None of these models is universally correct. A shared ingress is often the simplest browser experience because requests remain on one origin. Separate tunnels are useful when services need independent public lifecycles, direct external access, distinct hostnames, or realistic cross-origin testing. A hybrid model is appropriate when only some boundaries matter to the test.

Build a public origin map before creating tunnels

Start with an inventory of every connection that crosses a browser or external-system boundary. Internal calls between backend processes do not necessarily need public addresses. A frontend loaded in a browser, an OAuth redirect initiated by an identity provider, a webhook sent by an external platform, and a WebSocket opened from a remote browser do need routes that the initiating system can reach.

For each public interaction, record the caller, destination service, local listener, desired public address, protocol, path, and security requirements. Do not begin by copying local ports into several dashboard forms. First decide which listeners should be consolidated and which should remain independent.

The placeholders above are design notation, not Localtonet-assigned addresses. Replace them only after the dashboard has assigned the actual public URL or after a supported custom hostname has been configured. HTTP tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain as their Process Type. Availability and any plan-specific conditions can vary, so use only the values currently displayed for your account. Custom-domain DNS requirements should be taken from the current Localtonet documentation and dashboard rather than assumed.

Separate public and private service addresses

Keep two layers of configuration distinct. The private service map describes how processes reach each other locally. The public origin map describes how browsers and external systems reach selected entry points. A backend service that calls another backend over a local or container network should usually continue using that private address. Sending internal traffic out through a public tunnel and back into the same machine adds an unnecessary dependency and can complicate authentication, observability, and failure diagnosis.

It is helpful to keep one canonical configuration value for each public role rather than reconstructing URLs in multiple packages. For example, define a frontend origin, an API base URL, an authentication callback URL, and a WebSocket URL. The exact configuration mechanism depends on the frameworks in the monorepo, so this guide does not invent universal environment-variable names. Use the documented configuration interface of each application and make the generated client configuration consistent with the server configuration.

Decide whether paths are part of the service contract

A reverse proxy can route a public prefix such as /api to an API, but the API may expect requests at /, at /api, or under another base path. Decide whether the proxy preserves or removes the prefix. The application’s route generation, redirects, OpenAPI links, static resources, and cookie paths must agree with that decision.

Apply the same discipline to authentication callbacks and WebSockets. A callback path registered with an OAuth provider must be the path the application actually handles. A WebSocket path expected by the client must reach the correct upgrade-capable upstream. Merely forwarding the correct port is insufficient if the path contract is inconsistent.

When to use one reverse proxy and one HTTP tunnel

In the shared-ingress model, a local reverse proxy becomes the application’s single public entry point. The proxy listens on one local IP address and port. It serves or forwards the frontend at the root path, forwards API requests under a selected prefix, routes authentication paths to the appropriate service, and proxies WebSocket upgrades to the correct listener. A single Localtonet HTTP tunnel then targets the reverse proxy.

This model is usually attractive when the remote experience should resemble a conventional web application with one origin. Browser requests can use relative paths such as /api/projects instead of embedding a second hostname. Because the scheme, host, and port remain the same, ordinary same-origin API calls do not require CORS permission.

What the reverse proxy must handle

The proxy needs explicit route ownership. A broad frontend fallback can accidentally consume API or authentication paths, especially in single-page applications that return the main HTML document for unknown routes. Put specific service routes ahead of any generic frontend fallback according to the configuration semantics of the chosen proxy.

The proxy must also preserve the request information each upstream needs. Applications commonly use the external host and protocol when constructing redirects, absolute links, cookie settings, and callback addresses. Configure trusted proxy behavior deliberately within the application and reverse proxy. Do not blindly trust forwarding headers from arbitrary sources, since those headers can affect security-sensitive URL construction.

WebSocket forwarding deserves a specific route and configuration. An ordinary HTTP route can appear healthy while failing to preserve the protocol upgrade needed for a WebSocket connection. Confirm that the chosen reverse proxy supports WebSocket proxying and configure it using that proxy’s official syntax. There is no framework-neutral configuration file that is safe to paste into every stack.

Costs of the shared model

One public origin also creates one public failure boundary. If the reverse proxy stops, every routed service becomes unavailable through that tunnel. Route conflicts can make one service shadow another, and developers must maintain a proxy configuration as services are added or renamed. A shared ingress can also hide cross-origin bugs if the production system actually places the frontend and API on different origins.

Use one tunnel when a unified browser origin is the behavior you want to test, not merely because it creates fewer tunnel records. The architecture should represent the test objective.

When separate HTTP tunnels are the better boundary

Separate tunnels give selected services independent public origins. The frontend tunnel targets the frontend listener, the API tunnel targets the API listener, and another tunnel can target the authentication or WebSocket service if it genuinely needs an independent public entry point. The Localtonet client must run on a device that can reach every configured local target.

This approach is useful when teams need to test the same origin separation used in another environment, expose only one backend without the frontend, restart services independently, provide a dedicated webhook address, or diagnose a service without a reverse proxy between the relay and the application.

A hybrid arrangement often provides the best test surface

It is not necessary to expose every process in the same way. A practical hybrid can place the frontend, browser API, and application WebSocket behind one reverse proxy while giving a webhook receiver its own tunnel. Another option is to keep authentication under the shared browser origin but publish an independently tested API through a second tunnel.

Each additional origin should have a reason. If a service is used only by another local backend, keep it private. If a service must receive an external callback directly, needs independent lifecycle control, or is intentionally being tested across origins, a separate tunnel can be justified.

How the design affects CORS, cookies, OAuth, and WebSockets

CORS follows the browser origin, not the repository structure

A browser origin is determined by scheme, hostname, and port. Two services belong to different origins if any of those components differ. Paths do not create different origins, so https://PUBLIC_ORIGIN/ and https://PUBLIC_ORIGIN/api are same-origin. Conversely, a frontend and API on different public hostnames are cross-origin even if they come from the same monorepo.

When separate tunnels are used, configure the API to allow the exact frontend public origin required by the workflow. Avoid reflecting arbitrary origins or using a broad wildcard as a shortcut. If browser requests include credentials, CORS policy must explicitly support credentials and return a permitted origin rather than relying on a wildcard. The frontend must also use the credential behavior expected by the API.

Preflight requests can fail even when the main API method is correctly implemented. The API or proxy must handle the browser’s OPTIONS request and permit the requested method and headers. Diagnose the preflight separately from the application request.

Cookies have host, path, security, and same-site boundaries

Public HTTPS does not automatically make an existing local cookie design work. Check the cookie’s host or domain scope, path, Secure behavior, SameSite policy, expiration, and whether the browser request includes credentials.

Host-only cookies are generally easier to reason about when the frontend and authentication routes share one public host. Separate hosts require a deliberate session design. A cookie created for one host is not automatically available to an unrelated host. Even where sibling hostnames may qualify as the same site under browser rules, origin restrictions and credential handling still apply. Do not infer cookie behavior merely because hostnames look similar.

Inspect the actual Set-Cookie response and the browser’s cookie storage. Browser developer tools often explain why a cookie was rejected or excluded. Typical causes include a domain that does not match the public host, an incorrect callback path, a same-site policy incompatible with the navigation, or a frontend request that does not include credentials.

OAuth redirect URIs must match the active public topology

An OAuth redirect URI is part of the security boundary. Register the exact public HTTPS callback that the application uses, including the scheme, hostname, path, and any relevant port. A callback configured for a local address will not become correct merely because the application is reachable through a tunnel.

Keep the browser initiation URL, application callback handler, OAuth provider registration, and server-side redirect construction aligned. If a generated public hostname changes, update the provider registration and application configuration before testing again. A stable custom subdomain or custom domain can reduce callback churn where currently available to the account, but availability and DNS setup must be confirmed in the current dashboard and documentation.

Preserve and validate OAuth state, use the provider and framework’s documented security controls, and never place client secrets or tunnel authentication tokens in browser-visible configuration. A public callback address is not a substitute for OAuth validation.

WebSockets need the correct public scheme, path, and upgrade route

A page loaded over HTTPS should use a secure WebSocket address with the wss scheme. If the application constructs a local ws://localhost URL at build time, remote browsers will try to connect to their own machine or may block the connection as mixed content. Configure the client with the actual public WebSocket address or derive the address from the current page when the shared-origin design permits it.

For one shared origin, the local reverse proxy must forward the WebSocket route to the correct service and support the upgrade. For separate tunnels, the client must point to the WebSocket service’s public hostname and the service may need to validate the browser’s Origin header. Hot-reload systems can have framework-specific public-host, client-port, or allowed-host settings. Use the documented settings for the development server rather than assuming that an API WebSocket configuration also controls hot reload.

Configure the chosen public ingress with Localtonet

Before creating a tunnel, start every required service and verify it locally. For a shared design, verify the reverse proxy rather than testing only the individual upstream ports. For separate tunnels, verify each selected service on the exact local IP address and port that our client will target.

You need the Localtonet client on the device that can reach those listeners, a device-specific authentication token, an available relay server or region selected from the current product, and a completed origin map. Tokens and available server codes must be obtained from the current dashboard. Do not copy a token into documentation, source control, shell history shared with others, screenshots, or frontend configuration.

The shared model normally needs one Localtonet HTTP tunnel because the local reverse proxy is the only public target. The separate model needs one tunnel for each independently public service, not necessarily every service in the repository. For current setup details, use the Localtonet HTTP tunnel documentation alongside the fields displayed in your dashboard.

Verify the complete workflow from outside the local machine

Local verification and public verification answer different questions. A successful local request proves that a service is listening and can handle at least one request. A successful public request also verifies the running client, tunnel state, selected target, public routing, reverse-proxy behavior, and application handling of the external host and protocol.

Verify local listeners first

Test each service directly from the device running the Localtonet client. If using a reverse proxy, request every public route through the proxy’s local listener. Confirm that the frontend returns the expected document, API paths reach the API rather than the frontend fallback, authentication paths reach the intended handler, and WebSocket routes are configured for upgrades.

If the application runs in containers or virtualized environments, verify reachability from the client device rather than only from inside the application container. A service can be healthy inside its own network while remaining unreachable at the local IP address and port entered in the tunnel configuration.

Verify the public document and API routes

Open the assigned public HTTPS URL in a browser that is not relying on a local development proxy. Use the Network panel to inspect the frontend document, static assets, API requests, redirects, preflights, cookies, and WebSocket handshakes.

A basic command-line request can confirm the public HTTP response without depending on frontend JavaScript:

curl -i https://PUBLIC_ORIGIN/

Replace PUBLIC_ORIGIN with the actual assigned hostname. Test only routes that genuinely exist in the application. Do not assume that every service implements a /health endpoint.

For separate origins, test an API request with the same Origin value the browser will send. The following is a diagnostic pattern, not a universal API path:

curl -i \
  -H "Origin: https://FRONTEND_PUBLIC_HOST" \
  https://API_PUBLIC_HOST/KNOWN_API_PATH

Inspect the returned CORS headers and status. A command-line client does not enforce browser CORS, so a successful response alone does not prove that browser JavaScript can read it. The response headers must also satisfy the browser’s policy.

Run an end-to-end authentication test

Begin from the public frontend, follow the provider redirect, and verify the exact callback address in the browser. Confirm that state validation succeeds, the callback reaches the expected service, a session is established as designed, and the browser sends the session on the next relevant request.

Test in a clean browser profile or private window when old cookies could obscure the result. A stale cookie created for a previous generated hostname can make a configuration problem appear intermittent.

Verify both WebSocket channels if applicable

Test application WebSockets and hot reload independently. In browser developer tools, confirm that the requested URL uses the intended public host and wss scheme, that the handshake upgrades successfully, and that messages or reload notifications continue after the initial connection.

Finally, test the remote experience from another network or device where practical. This catches accidental dependencies on local DNS names, loopback addresses, browser extensions, local proxy settings, and cached service workers.

Troubleshoot by identifying the failing layer

Avoid changing CORS, proxy, OAuth, and tunnel configuration at the same time. Start at the local listener and move outward. The point where behavior changes usually identifies the responsible layer.

Use a layered diagnostic sequence

1. Confirm the target process is running.
2. Confirm the Localtonet client device can reach the configured local IP and port.
3. For shared ingress, confirm the reverse proxy routes each path to the expected upstream.
4. Confirm the Localtonet client is connected.
5. Confirm the tunnel is started.
6. Request the assigned public URL without relying on frontend JavaScript.
7. Inspect browser-origin behavior such as CORS, cookies, redirects, and WebSockets.
8. Test the complete user flow from an external browser.

If direct local service requests work but requests through the local reverse proxy fail, the tunnel is not yet the relevant layer. If the reverse proxy works locally but the public URL does not connect, inspect the client, selected target, and tunnel state. If public HTTP works but only browser JavaScript fails, investigate browser policy and client configuration.

Secure a publicly reachable development topology

A public HTTPS URL makes the selected service reachable from the internet while the tunnel and client are running. It does not add application authorization, remove unsafe debug behavior, or determine who should be allowed to call an endpoint. Treat the public origin as an internet-facing entry point.

Review development-only routes before exposure. Disable unnecessary debug panels and test utilities, restrict administrative operations, and avoid using real production data when a representative test data set is sufficient. If an external service sends webhooks or OAuth callbacks, validate signatures, state, nonces, timestamps, or other controls required by that protocol.

Be careful with proxy-aware application settings. Trust only the proxy chain appropriate to the deployment. Incorrectly trusting arbitrary forwarding headers can allow a request to influence generated URLs or security decisions. The exact trusted-proxy syntax depends on the server framework and must come from that framework’s current documentation.

Use separate tunnels when isolation is a security or operational objective, but do not assume separation alone creates authorization. Conversely, a shared reverse proxy can centralize route controls, but it should not become an accidental route to every listener on the machine.

Frequently asked questions