Share a FastAPI app

Share your FastAPI app with a public HTTPS URL, including the interactive /docs page.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A FastAPI app in main.py and Uvicorn installed

uvicorn main:app --reload

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

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

Check it worksCopy Anchor Link

Open https://my-app.hrzn.run/docs. On the first visit Horizon shows a Before you continue page. Select Continue to site. Swagger UI lists your routes. Expand one, select Try it out, then Execute.

The Horizon terminal prints one line per request:

  GET     200  /docs
  GET     200  /openapi.json
  GET     200  /items/

TroubleshootingCopy Anchor Link

A redirect goes to http://localhost:8000Copy Anchor Link

FastAPI redirects /items to /items/ when you declare the route with a trailing slash. The redirect builds its address from the Host header, which the CLI sets to localhost:8000. The browser then follows a link to your own machine.

Request the exact path, /items/, or declare the route without the trailing slash. Check the Location header with curl -i https://my-app.hrzn.run/items.

Do I need --proxy-headers or --forwarded-allow-ips?Copy Anchor Link

No. --proxy-headers is on by default, and Uvicorn trusts 127.0.0.1 and ::1, which is where the CLI connects from. Uvicorn only reads X-Forwarded-Proto and X-Forwarded-For. It ignores X-Forwarded-Host, and it skips an X-Forwarded-Proto value like https,http. So the flags don't change the host or scheme your app sees.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and the URL stays the same. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your appCopy Anchor Link

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

Next stepsCopy Anchor Link

• Read FastAPI's guide to running behind a proxy.
• Share a different stack: Flask or Django.