Chrome Local Network Access for APIs and WebSockets

Why Chrome Local Network Access matters to developers

A common development pattern starts with a public web application and a companion service running on the user's computer. The public page may call an API at http://localhost, connect to a loopback address such as 127.0.0.1, or open a WebSocket to a private address on the local network. This is useful for device controllers, desktop helpers, testing agents, local AI services, network diagnostics, and development tools.

The same pattern also crosses an important security boundary. A public website should not receive unrestricted access to services that happen to be reachable from a visitor's private network. Browsers are therefore adding and refining controls around requests from public origins to loopback and private-network destinations. Depending on the Chrome or Chromium version, security context, destination, permission state, and deployment policy, the browser may ask the user for permission, reject the request, or expose a diagnostic in DevTools.

Exact rollout details are especially sensitive to browser versions. Prompt wording, settings-page labels, enforcement coverage, enterprise policies, and the treatment of particular request types can change between Chrome releases. Chromium-based browsers may also adopt a change on different schedules. Before shipping instructions to end users, validate them against the current official documentation for the browser versions in your supported fleet.

Local Network Access behavior becomes particularly confusing because several browser and server security mechanisms can fail at roughly the same point in an application. A failed fetch() request might be caused by local-network restrictions, mixed content, CORS, a TLS problem, an unavailable server, or rejected credentials. A failed WebSocket can originate from browser network policy, an invalid secure WebSocket URL, a rejected HTTP Upgrade handshake, an application origin check, or an incorrectly configured server.

The most productive way to troubleshoot is to identify each layer separately. Start with the destination the browser is actually contacting, then check the page's security context, the network connection, the HTTP or WebSocket protocol exchange, and finally the application's own authorization rules.

Local Network Access, CORS, mixed content and WebSockets are different layers

It is tempting to group every browser networking error under CORS, but that often leads to the wrong fix. Local Network Access, CORS, mixed-content rules, TLS validation, and WebSocket handshake checks solve different problems. More than one can apply to the same request.

Local Network Access is destination-sensitive

The significant architectural detail is where the browser believes it is connecting. If JavaScript loaded from a public origin requests a loopback or private address, the browser can classify that as access from a less-private address space into a more-private one. Using a friendly public-looking hostname does not necessarily change the classification if DNS ultimately resolves that hostname to a loopback or private address.

This is why replacing 127.0.0.1 with a DNS record that still resolves to 127.0.0.1 is not a reliable solution. The visible hostname and the resolved network destination are separate pieces of information. Browser implementations can use the resolved address when applying local-network protections.

CORS controls HTTP response access

CORS applies when browser JavaScript makes an HTTP request across origins. An origin is defined by scheme, hostname, and port. A page at https://app.example.test and an API at another hostname are cross-origin even when both are public and use HTTPS.

The API must return CORS headers appropriate for the requesting origin and request type. Some requests trigger a preflight request using the OPTIONS method. Authentication headers, non-simple content types, and non-simple methods commonly affect whether a preflight is required. A tunnel does not synthesize an application's CORS policy, and changing the network path does not automatically allow the browser to read the response.

Avoid responding with an unrestricted origin policy merely to silence an error, especially when credentials or sensitive data are involved. Define the frontend origins that genuinely need access, allow only the required methods and headers, and test both preflight and actual responses.

Mixed content concerns secure and insecure schemes

A page loaded over HTTPS operates as a secure context. Browsers generally restrict active connections from that page to insecure resources. A request from an HTTPS page to an http:// API or a ws:// WebSocket may therefore be blocked before application-level behavior becomes relevant.

For a public HTTPS page, use an HTTPS API URL and a secure wss:// WebSocket URL where the browser-facing endpoint supports it. Do not disable browser security features as a routine development fix. That produces a machine-specific exception and hides problems that users will still encounter.

WebSockets start as HTTP but are not governed exactly like fetch

A WebSocket connection begins with an HTTP request asking the server to upgrade the connection. The server must recognize the route, accept the upgrade, and return the expected status and headers. After that handshake, the connection becomes a bidirectional WebSocket stream.

The browser includes an Origin header in the handshake. WebSocket servers should validate this origin where appropriate. CORS response headers are not a replacement for a WebSocket origin allowlist, and a successful HTTP API request does not prove that a WebSocket route is configured correctly.

How a public HTTPS tunnel changes the browser-facing architecture

With the direct-local pattern, the browser receives a public page and then attempts to connect inward to a loopback or private-network address. The browser is an active participant in that local-network transition. Local Network Access protections are designed around precisely this kind of boundary.

With Localtonet, our client application runs on the device that can reach the local service. The client establishes an outbound connection to a Localtonet relay server. An HTTP tunnel then provides a public URL that forwards traffic to the configured local IP address and port. The browser contacts the assigned public endpoint rather than requesting localhost or a private IP directly.

This changes the network path. It does not disable or bypass a browser permission. The browser is simply given a different destination. The public request reaches our relay, and the already-established outbound tunnel carries the traffic to the selected local target.

Because the Localtonet client initiates the relay connection outbound, the workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup. The tunnel remains available only while the selected client device is connected and the tunnel is running.

This architecture is useful when a developer needs to test a public frontend against a local API, share a development endpoint with a remote tester, exercise a webhook or callback workflow, or validate browser behavior from a clean public origin. It also makes the security consequences more visible: the local application is now reachable through a public endpoint and must be prepared accordingly.

Prerequisites and information to collect

Before creating a tunnel, verify the local application independently. Tunneling cannot repair a service that is not running, listening on the wrong interface, using an incorrect route, rejecting the expected host or origin, or failing its own startup checks.

Collect the following information:

• The local IP address reachable from the device running the Localtonet client.
• The actual listening port reported by the application or its configuration.
• An HTTP endpoint suitable for verification, such as an existing health, status, or version route.
• The WebSocket path, if the service exposes WebSockets.
• The public frontend origin that the API or WebSocket server should permit.
• The application's authentication method and the least-privilege test account or token strategy.
• A Localtonet device/auth token for the client that will run the tunnel.
• An available Localtonet relay server or region selected from the current dashboard.

Device tokens identify the client device and must be treated as secrets. Do not place them in browser JavaScript, source control, screenshots, support tickets, or article examples. Relay server codes and available regions can change by current product configuration, deployment, or plan, so select an available value from the dashboard rather than copying a hardcoded example.

The local bind address matters. A service bound only to loopback can normally be reached by a Localtonet client running on the same machine, provided the configured target uses the correct loopback address and port. If the client runs in another container, virtual machine, or physical device, that device's localhost refers to itself, not to the application host. In that case, configure a target address that is actually reachable from the client environment and secure that listener appropriately.

Prepare and verify the local API or WebSocket service

If local HTTP succeeds but the local WebSocket fails, solve the WebSocket problem before adding the tunnel. Check the exact route, scheme, expected subprotocol, authentication requirements, and server logs. A normal HTTP response on the root path does not establish that the WebSocket upgrade path works.

If the API is designed only for same-origin use, decide whether to keep that model. One option is to have the public application server call the API server-side rather than letting browser JavaScript call it directly. Another is to configure a specific cross-origin browser policy. The correct choice depends on the application's trust model and cannot be safely replaced by a universal CORS setting.

Configure the Localtonet HTTP tunnel

Once the service works locally from the client device, create the public path. The workflow below follows the established Localtonet tunnel lifecycle without inventing version-specific dashboard fields. Names and available selections can vary with the current dashboard, client version, region, or plan.

For the current dashboard workflow and available HTTP tunnel options, consult the Localtonet HTTP tunnel documentation. The dashboard is authoritative for the server selection, assigned address, and options available to your account at configuration time.

Verify the public API and WebSocket path

Verification should progress from simple transport checks to browser-specific behavior. Testing everything through the full frontend immediately can hide the layer that failed.

1. Test a simple HTTPS request

Request a known route through the assigned public URL. Replace the placeholder hostname and path below with the actual URL and an existing route from your application:

curl -i https://PUBLIC_HOST/EXISTING_HEALTH_ROUTE

Confirm that the status and body match the local result. A different response may indicate a wrong route, an application host restriction, authentication behavior, or a target configuration problem. Do not assume that an HTTP 404 means the tunnel is offline. A 404 often means the connection reached an HTTP server but requested a route that server does not provide.

2. Test browser fetch behavior

After direct HTTPS verification succeeds, point the frontend at the public API origin. A minimal diagnostic request can help isolate browser behavior:

const apiUrl = "https://PUBLIC_HOST/EXISTING_API_ROUTE";

fetch(apiUrl, {
  method: "GET",
  credentials: "omit"
})
  .then(async response => {
    console.log("Status:", response.status);
    console.log("Body:", await response.text());
  })
  .catch(error => {
    console.error("Request failed:", error);
  });

Choose the credential mode according to the application's actual authentication design. The example deliberately does not assume cookies or an authorization header. If the application uses credentials, configure its CORS policy carefully. Credentialed cross-origin requests have stricter requirements than unauthenticated public requests.

Inspect the Network panel for an OPTIONS request. If the preflight fails, compare the requested origin, method, and headers with the API's response. If no request appears at all, inspect the Console for a mixed-content, browser policy, DNS, or malformed-URL error.

3. Test the secure WebSocket URL

For a page loaded through HTTPS, construct the browser-facing WebSocket URL with the secure wss:// scheme and the application's existing WebSocket path:

const socket = new WebSocket("wss://PUBLIC_HOST/EXISTING_WEBSOCKET_PATH");

socket.addEventListener("open", () => {
  console.log("WebSocket connected");
});

socket.addEventListener("message", event => {
  console.log("WebSocket message:", event.data);
});

socket.addEventListener("error", event => {
  console.error("WebSocket error:", event);
});

socket.addEventListener("close", event => {
  console.log("WebSocket closed:", event.code, event.reason);
});

This code tests connection events but does not assume an application message format. Send only messages documented by your service. If the server requires a WebSocket subprotocol, authentication exchange, or initial subscription message, add it according to that application's specification rather than guessing.

In Chrome DevTools, select the WebSocket request in the Network panel. Review the handshake URL, request headers, response status, frames, close code, and timing. A rejected upgrade differs from a connection that opens and then closes because the application did not receive an expected authentication message.

4. Compare direct-local and public-endpoint behavior

Run a controlled comparison:

• Load the frontend from its intended public HTTPS origin.
• Attempt the original direct-local URL and record the first browser diagnostic.
• Attempt the Localtonet public HTTPS or secure WebSocket URL.
• Compare whether a request was sent, whether TLS completed, and whether the application returned a response.
• Check application logs for both attempts.

If the direct-local request is affected by Local Network Access behavior but the public endpoint reaches the service, the difference is architectural: the browser is no longer initiating a connection to a loopback or private destination. This does not imply that the browser's security controls were disabled.

5. Test a clean browser state

Browser permissions can be remembered per origin, and cached application configuration can preserve old URLs. Test with a clean profile or carefully reset the relevant site data and permissions using the current browser UI. Do not publish exact menu labels until they have been checked for the Chrome versions your audience uses because those labels can change.

Also test at least one browser outside your normal development profile. Extensions, enterprise configuration, manually changed flags, cached service workers, and previously granted permissions can make a developer's browser behave differently from a user's installation.

Secure the API and WebSocket before sharing the URL

A local service often begins with assumptions that stop being valid when it receives a public endpoint. It may trust every caller, expose detailed error messages, provide a debug console, allow broad filesystem operations, or bind administrative and user-facing routes to the same listener. Review those assumptions before starting the tunnel.

Do not put durable secrets in frontend code

Any secret shipped to browser JavaScript can be inspected by the user and may appear in logs, source maps, network captures, browser storage, or error reports. Prefer a user authentication flow or a short-lived credential design appropriate to the application. Avoid credentials in URLs because URLs can be copied, logged, retained in history, and included in diagnostic output.

Validate WebSocket clients after connection

A successful WebSocket handshake should not grant unlimited access. Authenticate the session using the application's supported design, enforce authorization for subscriptions and commands, and handle token expiry or revocation. Limit message sizes and reject unexpected message types. Close connections cleanly when authorization fails.

Use narrow CORS rules

Define the exact frontend origins that need browser access. Permit only required methods and headers. If cookies or other browser-managed credentials are involved, review cross-site cookie attributes, CSRF protections, and the application's credential model together. CORS is not a CSRF defense by itself, and allowing an origin is not the same as authorizing every user from that origin.

Keep development and production boundaries clear

A temporary tunnel is valuable for testing, demonstrations, and controlled remote access, but it should not silently turn a development process into an unmanaged production service. Document who owns the tunnel, when it should run, what data may pass through it, and how access is revoked. Recheck plan, region, and deployment requirements in the current dashboard instead of assuming that every capability is available in every subscription.

Troubleshooting APIs, CORS and WebSocket connections

The service is listening on the wrong interface

Confirm the application's actual listener. If both the application and Localtonet client run on the same host, a loopback listener may be sufficient. If they run in separate containers, machines, or network namespaces, loopback is not shared. Change the application binding only when necessary, and avoid exposing it broadly to the LAN without appropriate host firewall and application controls.

The tunnel targets the wrong port

Development tools sometimes use separate ports for the frontend, API, and WebSocket server. Proxy configuration can make them appear to share one origin during local development even when separate processes handle them. Verify which process receives the desired route and configure the local target accordingly. Do not select a port merely because it is common for the framework.

The application rejects the public host

Some frameworks validate the HTTP Host header to reduce DNS rebinding and accidental exposure. If logs show a rejected host, add the assigned hostname using the framework's documented allowlist mechanism. Do not disable host validation globally. The exact setting is framework-specific and should not be guessed.

The CORS preflight fails

Verify that the server handles OPTIONS on the requested route and returns headers consistent with the actual frontend origin, method, and request headers. Redirects, authentication middleware, and generic error handlers can interfere with preflight requests. Inspect the preflight response itself rather than changing unrelated browser settings.

The WebSocket route fails while HTTP works

Check that the browser uses wss:// for a public HTTPS page and that the WebSocket path is exact. Inspect the handshake response. A 401 or 403 points toward authentication, authorization, or origin validation. A 404 points toward routing. A successful upgrade followed by an immediate close usually indicates an application-level requirement, such as a missing subprotocol or authentication message.

The page still contains localhost references

Search runtime configuration, generated bundles, environment-specific configuration, service workers, and browser storage for the old local URL. A frontend may update its HTTP API base URL while retaining a separate localhost WebSocket URL. Clear stale application caches carefully and verify the final URL in DevTools.

The browser behavior differs across users

Compare browser versions, Chromium variants, site permissions, enterprise policies, extensions, and secure-context status. Local Network Access is an evolving browser area, so do not assume identical behavior across Chrome, Edge, Brave, Opera, Firefox, Safari, or older releases. Confirm current behavior with official documentation and a representative test matrix before giving end users exact prompt instructions.

Frequently asked questions