Test a mobile app against your local API

Point an iOS, Android, React Native or Expo app at the API on your laptop. The tunnel gives your phone or emulator a public HTTPS URL.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• An API running on your machine, for example on http://localhost:3000
• A mobile app you can rebuild or reload with a new base URL
• Optional: a reserved subdomain for -s, so the URL in your app doesn't change. Reserve one on the Subdomains page.

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

EXPO_PUBLIC_API_URL=https://my-app.hrzn.run

const apiUrl = process.env.EXPO_PUBLIC_API_URL;

export async function getProfile() {
  const response = await fetch(`${apiUrl}/api/profile`, {
    headers: { Accept: "application/json" },
  });
  return response.json();
}

import { WebView } from "react-native-webview";

export function PreviewScreen() {
  return (
    <WebView
      source={{
        uri: "https://my-app.hrzn.run",
        headers: { "x-hrzn-skip-warning": "1" },
      }}
    />
  );
}

iOS and Android security rulesCopy Anchor Link

You don't need to change either platform's network settings, because the tunnel is HTTPS.

• iOS: App Transport Security (ATS) is on by default. It requires secure connections: TLS 1.2 or later, strong ciphers and forward secrecy. A plain http:// URL fails unless you add an exception. An https:// tunnel URL doesn't need one.
• Android: Apps that target Android 9 (API level 28) or later block cleartext HTTP by default. HTTPS needs no configuration.

Don't set NSAllowsArbitraryLoads or cleartextTrafficPermitted="true" to reach a tunnel. You don't need them, and Apple triggers App Store review for NSAllowsArbitraryLoads.

Check it worksCopy Anchor Link

Trigger a request in your app. Your Horizon terminal prints one line per request:

  GET     200  /api/profile

Open the Request log link to see recent requests in the dashboard.

TroubleshootingCopy Anchor Link

My app gets an HTML page instead of JSONCopy Anchor Link

The request got the Before you continue page. Your client sends a browser user agent. Add the x-hrzn-skip-warning header to the request. See the WebView step above.

The request fails on iOS with an App Transport Security errorCopy Anchor Link

Your app still calls an http:// URL. Use the https:// tunnel URL. Check that nothing hard-codes the old http://localhost base URL.

The request fails on Android with a cleartext errorCopy Anchor Link

Your app still calls an http:// URL. Use the https:// tunnel URL.

The app still calls the old URLCopy Anchor Link

Do a full reload after you change .env. In Expo, a variable needs the EXPO_PUBLIC_ prefix and static process.env.EXPO_PUBLIC_API_URL access.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s. Restart with -s my-app. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your APICopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that your API runs on the port in the hrzn tunnel command.

Next stepsCopy Anchor Link

• Share a local API
• Expose a local WebSocket server