Open localhost on your phone
Checked against the qURL™ CLI 3.4.1 source and documentation on October 9, 2026. Link and session behaviour is tested separately.
Content updated October 18, 2026. The verification date above records the original review; later behaviour checks are dated in the guide.
How do I open my local app on my phone?
Publish the app with qurl publish, run qurl share, and open the link on your phone. It works on mobile data as well as Wi-Fi, without finding your laptop’s LAN IP or binding the app to 0.0.0.0, and without an account.
What you need
- An HTTP app running on your computer
- The qURL CLI 3.4.1 or later
- A phone with a current browser (iOS 16 or later, or a recent Chrome); it does not need to be on the same network
Steps
Install the qURL CLI
On macOS, install it with Homebrew. On Linux and Windows, download the package for your platform from the latest release; the CLI page lists each one. Nothing asks you to sign up.
brew install layervai/tap/qurl qurl --versionPublish the app
The first publish creates this device’s identity, starts a background service that keeps serving after you close the terminal (while you stay logged in), and prints the app’s CRID, its stable ID. The Access row says who can open the app: a plain publish makes it private from qurl 3.4.1 on. qurl share turns the CRID into an access link, and the link is what you send.
qurl publish http://127.0.0.1:3000Published Target: http://127.0.0.1:3000 Access: private — only you and the people you allow can open it Status: serving CRID: ae4jqpd7eaoslq7jinmjv4yikgzmcxgpjfsuobiniqnko32lpw743ivbeyha
Get the link onto your phone
Show the link as a QR code in your terminal and scan it with the phone’s camera, so no other app or service opens it first. Avoid email and chat apps that preview links: a scanner that runs the page could use the link’s one opening. Open it on the phone, not on your computer. With -q, qurl share prints only the link, without the expiry line; links for apps published from the CLI are single-use by default and expire within 24 hours. qrencode is a separate install (on Linux, use your package manager, for example sudo apt install qrencode).
brew install qrencode qurl share <CRID> -q | tr -d '\n' | qrencode -t ansiutf8
What the recipient sees
Your phone’s browser lands on the app over HTTPS. The session is tied to the network the phone opened the link from, not to the phone itself. If the phone switches between Wi-Fi and mobile data, or a VPN turns on, the app stops loading; run qurl share again and open the new link.
Troubleshooting
| If you see | Do this |
|---|---|
| The app loaded on the phone, then stopped responding | The phone changed network (Wi-Fi to mobile data, or a VPN or iCloud Private Relay switched on), or the session ended after its hour. Run qurl share again and open the new link on the phone; add --session-duration for a longer session, up to 24 hours. |
| The page loads but API calls, images, or sockets fail on the phone | The app is calling http://localhost:PORT or another absolute URL. On the phone, localhost is the phone itself. Use relative URLs, or proxy the API through the same dev server. |
| Vite shows “Blocked request. This host is not allowed” | Add .qurl.site to server.allowedHosts and restart Vite. See the dev server guide. |
| qurl publish says the local app is not accepting TCP connections | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows [::1]), publish 'http://[::1]:PORT' instead. Keep the quotes: zsh treats the brackets as a pattern. |
| The recipient sees “Access link invalid” | The link was already used or has expired. Run qurl share again and send the new link. |
| The recipient sees “Resource not found” | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link. |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, or asks you to log in | You have a CLI older than 3.0. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release again. After updating, qurl --version should print 3.4.1 or later. |
| publish prints no Access: line, or the Access: line says public and you did not ask for public | With no Access: line, the CLI is older than 3.4.1: on macOS run brew update, then brew upgrade qurl; elsewhere install the latest release again. A resource that an older CLI published is public unless you published it with --private, and anyone who has the CRID of a public resource can open it. To make a public resource private, run qurl delete <CRID> and publish again with qurl 3.4.1 or later. The new resource is private and has a new CRID. |
| publish says this Linux session “can’t reach a systemd user manager” | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot. |
Frequently Asked Questions
Does my phone need to be on the same Wi-Fi?
No. The phone opens the link and the app over ordinary HTTPS through LayerV, so it can be on mobile data or any network that allows web browsing. If it changes network while you test, open a fresh link.
Why not bind the app to 0.0.0.0 and use my LAN IP?
That makes the app reachable by every device on the network, needs both devices on the same network, and fails on guest and public Wi-Fi that isolate devices from each other. The phone would also load it over plain http://, where browsers block the camera, geolocation, and service workers. A qURL link keeps the app on localhost and serves it over HTTPS to the network the link was opened from.
Who else can reach my app while the link is open?
Opening the link admits the network address it was opened from for the session, which lasts 1 hour by default. Other devices that share that public IP address, such as people on the same office or café network or VPN, can reach the app until the session ends. By default a link admits whoever opens it; access rules set through the API, such as IP allow and deny lists, can restrict that. Keep your app’s own sign-in for anything sensitive.