Skip to main content
← All guides

Password-protect a local app you’re sharing

Why qURL here

An email invitation beats a password: each person gets in with their own passkey, so there is no shared secret to leak or rotate. When a group does want one password, Caddy asks for it in front of the app, and qURL™ keeps the app itself off the public internet.

See how LayerV compares to ngrok →

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.

  1. 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 share link 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.

  2. 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 --version
  3. Install 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 version
  4. Make 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 > hash
  5. Put 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 Caddyfile
  6. Check the password before you share

    Ask as qURL will, with a qurl.site Host header. Expect 401 without the password and 200 with it; anything else means the Caddyfile or the app port is wrong, so stop and fix it before publishing.

    curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: c-test.qurl.site' http://127.0.0.1:8080/
    printf 'user = "reviewer:%s"\n' "$(cat ~/.qurl-review/password)" | curl -K - -s -o /dev/null -w '%{http_code}\n' -H 'Host: c-test.qurl.site' http://127.0.0.1:8080/
    401
    200
  7. Make sure the app’s own port is not shared

    A resource for the app’s own port bypasses the password. Check all resources, including stopped ones that qurl start could reopen, and all three loopback hostname forms. Change 3000 here too if your app uses another port. If this prints any CRIDs, stop and tell the user; close active shares with qurl stop <CRID>, and delete them with qurl delete <CRID> only after they agree: deleting is permanent. Do not continue while an unprotected share can still be used.

    qurl list -o json > ~/.qurl-review/resources.json &&
    jq -r '.resources[] | ((.target_url // "") | ascii_downcase | sub("^https?://"; "") | rtrimstr("/")) as $target | select(["127.0.0.1:3000", "localhost:3000", "[::1]:3000"] | index($target)) | .crid' ~/.qurl-review/resources.json
  8. Publish 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/crid
  9. 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 stop with 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

Troubleshooting
If you seeDo this
caddy hash-password exits with an “EOF” errorIts 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 promptThe 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
More troubleshooting
If you seeDo this
The browser keeps asking for the passwordThe 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 passwordThe 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 connectionsStart 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: lineYour 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.

Or use the CLI →

Book a pilot

Tell us what to hide. We’ll scope a pilot.

Enterprise starts with a paid pilot on one application, typically 60 to 90 days, credited in full toward year one if you convert within 60 days. After that, an annual package sized to what you protect, not per seat.