# Password-protect a local app you’re sharing

> Password-protect a shared localhost app: invite the person’s email with qURL so only they get in, or put a Caddy password in front and share it through qURL.

Source: https://layerv.ai/guides/password-protect-localhost/

---

[← All guides](https://layerv.ai/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 →](https://layerv.ai/compare/qurl-vs-ngrok/)

Copies a prompt for any agent that runs commands. 

## What you need

- The app running on this machine, listening on 127.0.0.1
- The qURL CLI 3.4.1 or later
- Caddy 2.8 or later (earlier releases call the directive basicauth)
- openssl, curl and jq, which most macOS and Linux machines already have

Content updated October 29, 2026.

## 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. ### Make 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'
```
10. ### 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.
11. ### 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.

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 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. |

__More troubleshooting__
| 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 →](https://layerv.ai/guides/share-from-a-container-or-ci/)                                                                                                                                                                                                  |
| 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.

## Related Resources

[Guide: Give an external reviewer temporary access to localhost →](https://layerv.ai/guides/share-localhost-with-temporary-access-link/) [Guide: Give a contractor temporary access →](https://layerv.ai/guides/give-a-contractor-temporary-access/) [Guide: Revoke access to a shared app →](https://layerv.ai/guides/revoke-access-to-a-shared-app/) [ngrok alternatives with authentication →](https://layerv.ai/compare/ngrok-alternatives-with-auth/) [Guide: Switch from localtunnel →](https://layerv.ai/guides/switch-from-localtunnel/) [qURL vs ngrok →](https://layerv.ai/compare/qurl-vs-ngrok/) [qURL vs Cloudflare Quick Tunnels →](https://layerv.ai/compare/qurl-vs-cloudflare-quick-tunnels/) [Guide: Allow a tunnel’s hostname in your dev server →](https://layerv.ai/guides/allow-tunnel-hostname-in-dev-server/) [Caddy docs: basic\_auth ↗](https://caddyserver.com/docs/caddyfile/directives/basic%5Fauth)

## 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 →](https://layerv.ai/cli/)



---

*This markdown version is auto-generated from [https://layerv.ai/guides/password-protect-localhost/](https://layerv.ai/guides/password-protect-localhost/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

