Help Center / api

Share a local app with osir tunnel

osir tunnel gives a web app running on your own computer a public HTTPS address, so you can show work in progress, receive webhooks, or open the thing on a real phone without deploying anything.

Before you start

Install the OSIR CLI 1.3.0 or later and check it:

osir --version

Then sign in once:

osir auth login

Open a tunnel

osir tunnel 3000

+------------------------------------------+
|  https://crisp-willow-knix.osir.run      |
+------------------------------------------+
Forwarding https://crisp-willow-knix.osir.run -> http://localhost:3000
Anyone with this link can reach your app. Press Ctrl+C to stop.

Share the link. It works until you press Ctrl+C.

Choosing what to expose

You type	Forwards to
`osir tunnel 3000`	`http://localhost:3000`
`osir tunnel localhost:8080`	`http://localhost:8080`
`osir tunnel http://127.0.0.1:5000`	`http://127.0.0.1:5000`
`osir tunnel https://localhost:8443`	a local server that speaks HTTPS

For HTTPS targets on your own machine, self-signed certificates are accepted. For any other host, the certificate is verified normally.

Scripts and CI

Use -o json to get a machine-readable line when the tunnel is ready:

osir tunnel 3000 -o json

{"status": "ready", "target": "http://localhost:3000", "url": "https://crisp-willow-knix.osir.run"}

Dev servers that check the host name

Your app receives the public host name in the Host header. If it rejects it, allow .osir.run:

Vite: server: { allowedHosts: ['.osir.run'] }
webpack-dev-server: devServer: { allowedHosts: ['.osir.run'] }

Reconnects and maintenance

If the connection drops, the CLI reconnects automatically and keeps your address when it can. Before planned maintenance, osir.run warns the CLI and holds your address for 120 seconds. You will see:

The edge is restarting; your address is held for 120s

Your login is refreshed automatically. A brief network outage, such as closing the laptop lid, does not sign you out.

If your app is not running

Visitors see an osir.run page explaining that the tunnel is up but nothing is answering at your local address. Start your app and they can reload.

Reference

osir tunnel <port | host:port | url> [flags]

Flag	Description
`-o json`	Machine-readable output
`--server`	Tunnel service to use (default https://osir.run, env `OSIR_TUNNEL_SERVER`)
`--auth`	Shared secret for a private tunnel service (env `OSIR_TUNNEL_AUTH`)

Good to know

The address is random and changes each time you start a new tunnel.
Anyone with the link can reach your app. Do not expose admin panels or databases.
Every tunnel is recorded against the account that opened it.
Report abuse to abuse@osir.com.

See also: Introducing Osir Tunnel and the developer documentation.