Steps
You may not need a password: publish the app with qURL as invite-only and invite the person’s email, so only they get in, with no shared secret to leak. When several people should share one password, put Caddy’s basic_auth in front of the app on 127.0.0.1 and publish that port with qURL. A coding agent can run every step.
Decide what the password is for
For named people, skip the password: a qURL email invitation (qurl 3.6.0 or later) lets in only the addresses you invite, each with its own passkey, and the reviewer guide shows it. For one visit, a
qurl sharelink opens once and expires on its own. Add a password when several people should share one, or as a second check on top of a link. The steps below add one, and each command runs without a prompt, so a coding agent can run them as written.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 --versionInstall Caddy 2.8 or later
Caddy is a single-binary web server that adds a password with a few lines of config. Check that caddy version prints v2.8.0 or later. On Linux, use Caddy’s official packages: a distribution’s own package can be older than 2.8, where basic_auth is still called basicauth.
brew install caddy caddy versionMake a password and its hash
Generate the password rather than asking for one, and keep it in a file in ~/.qurl-review, outside the project, so it never lands in a commit and survives between shells. Pipe it to caddy hash-password, which prints a bcrypt hash: the input must end in a newline, as openssl’s does, or caddy hash-password exits with an EOF error. Never print the password in logs or command output; it is shown once, at the handoff.
mkdir -p ~/.qurl-review && chmod 700 ~/.qurl-review && cd ~/.qurl-review (umask 077 && openssl rand -base64 18 > password) caddy hash-password < password > hashPut the password in front of the app
Write the Caddyfile and start Caddy in the background; caddy start returns once it is serving. Change 3000 to your app’s port, and 8080 if lsof -iTCP:8080 -sTCP:LISTEN shows it taken. http://:8080 answers any hostname, which matters: requests through qURL arrive with a qurl.site Host header, and a site address of http://127.0.0.1:8080 answers them with an empty page. bind 127.0.0.1 keeps the password port off your network, and reverse_proxy passes the Host header on, so a dev server that checks hosts still needs qurl.site allowed.
cd ~/.qurl-review cat > Caddyfile <<EOF http://:8080 { bind 127.0.0.1 basic_auth { reviewer $(cat hash) } reverse_proxy 127.0.0.1:3000 } EOF caddy start --config CaddyfilePublish the password port
Publish port 8080, not the app. Save the full reply before checking it so a failed privacy check cannot hide the resource that was created. The block prints the CRID only for a private resource and exits unsuccessfully otherwise. On failure, do not share: inspect publish.json for a returned CRID, report it to the user, and close that resource with
qurl stop<CRID>; ask before permanently deleting it. Save the validated CRID: the next commands take it.qurl publish http://127.0.0.1:8080 -o json > ~/.qurl-review/publish.json && jq -er 'select(.private == true) | .crid // empty' ~/.qurl-review/publish.json > ~/.qurl-review/crid && cat ~/.qurl-review/cridMake a one-time link
Give the session enough time for the work. The jq check prints the link only when it is single-use. The link is a secret: do not open it to test it, because opening it uses it up.
qurl share "$(cat ~/.qurl-review/crid)" --ttl 24h --session-duration 8h -o json | jq -er 'select(.single_use == true) | .qurl'Hand over the link and the password separately
Give the user the link in one message and the password in another, and suggest they send them to the reviewer through different channels, such as the link in a direct message and the password on a call, so one leaked message is not enough. Tell them the reviewer’s browser will ask for a username, reviewer, and that password. A reviewer who comes back needs a fresh link from
qurl share; the password stays the same.Change the password or end access
To change the password, run the hash step and the cat > Caddyfile command again, but not caddy start, which fails while Caddy is running; then caddy reload. The old password stops working at once and open sessions need the new one. If you changed port 8080 earlier, use your port in every command. To end access, run
qurl stopwith the CRID and caddy stop; then delete ~/.qurl-review if the review is over.caddy reload --config ~/.qurl-review/Caddyfile # after writing a new hash and Caddyfile qurl stop "$(cat ~/.qurl-review/crid)" # end access through qURL caddy stop # stop the password proxy
What the recipient sees
The reviewer opens the link and their browser asks for a username and password, its own sign-in box rather than a page of yours.
More
After the right password they see your app. Opening the link a second time shows “Access link invalid”; the password alone does not get them in without a link.
Troubleshooting
| If you see | Do this |
|---|---|
| caddy hash-password exits with an “EOF” error | Its input did not end in a newline. Read the password from the file openssl rand wrote, which ends in one, as the hash step does. |
| Caddy answers 200 with an empty page and no password prompt | The site address does not match the qurl.site Host header. Use http://:8080 in the Caddyfile, not http://127.0.0.1:8080 or localhost:8080, then caddy reload. |
Show 9 more fixes
| If you see | Do this |
|---|---|
| The browser keeps asking for the password | The username is not reviewer, or the hash does not match the password file. Run the hash and Caddyfile steps again, then caddy reload. |
| The app opens without asking for a password | The link points at the app’s own port. Run the check for the app’s port, delete that resource with qurl delete <CRID> once the user agrees, and share the CRID of port 8080. |
| The page says “Blocked request. This host … is not allowed” | Caddy passed the qurl.site Host header to your dev server, which refused it. Allow qurl.site in the dev server as the hostname guide shows for your framework. |
| 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, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. 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”, asks you to log in, or prints no Access: line | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default. |
| 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. Container and CI setup → |
| 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
Can my coding agent do this for me?
Yes. Paste this into Claude Code, Cursor, Codex or another agent that can run commands: “Put a password on the app I’m running and share it with qURL. Download https://layerv.ai/guides/password-protect-localhost.md with curl, read all of it, and follow it step by step. Give me the link and the password as two separate messages.” Every step runs without a prompt, and the password stays in ~/.qurl-review, outside your project. Agents that fetch pages through a web tool often get a summary instead of the page, which is why the prompt asks for curl.
How do I password-protect an ngrok URL?
An ngrok Traffic Policy can add a basic-auth action, but the ngrok URL stays public and the password is all that guards it. With qURL the app has no public address at all, and an email invitation needs no password: each person gets in with their own passkey.
Does localtunnel have a password?
Not one you choose. localtunnel’s maintainer says browser visitors first meet a page asking for a “tunnel password”, which is the public IP address of the machine running the tunnel, so anyone you send it to can pass. For a password you set, put Caddy’s basic_auth in front of the app and share it through qURL, as this guide does.
Can I password-protect a Cloudflare Quick Tunnel?
Not with a password. cloudflared tunnel --url with --allowed-mail asks each browser visitor for a one-time PIN sent to an allowed email address, and changing the addresses means restarting cloudflared, which gives a new trycloudflare.com hostname. With qURL, the app has no public address, and an invite-only address checks each person’s email with no restart and no new hostname.
Can I use nginx basic auth instead of Caddy?
Yes. Create an htpasswd file, then in an nginx server block set listen 127.0.0.1:8080 default_server, auth_basic and auth_basic_user_file, and proxy_pass to your app with proxy_set_header Host $host. default_server matters for the same reason as Caddy’s http://:8080: requests through qURL carry a qurl.site Host header. Publish port 8080 with qurl publish.
Can I password-protect a Vercel or Netlify preview instead?
Vercel password protection is not on the Hobby plan, and Netlify password protection is not on the free plan, and either way a preview is a deployed copy. qURL shares the live app on your machine with no deploy: invite people by email, or put a Caddy password in front.
Is a password safer than a qURL one-time link?
They work together: a qURL one-time link opens once, for whoever holds it, and a password stops anyone who got the link from using the app. For named people, a qURL email invitation does both jobs on its own, because only the invited address can get in.
Who else can reach my app while it’s shared?
Only the people you let in. With an invitation, only the invited address gets in, with its own passkey, and strangers cannot ask for access. After a browser opens a one-time link, another browser on the same public IP cannot use its access; a script or agent that opens it without a browser is admitted by its network address instead. Keep your app’s own sign-in for anything sensitive.
Does my computer have to stay on?
Yes. The app is served from your machine, so the machine and the app must be running and connected. The background service reconnects after sleep, but the app is unavailable while the machine is asleep.
Or have your coding agent do it
Paste this into Claude Code, Cursor or Codex in the project whose app is running. The agent follows this guide, keeps the password out of your project, and gives you the link and the password separately.