# Private localhost access for AI agents

> Give another AI agent private access to your local app with qURL device keys: no email and no account. The recipient sends its public key; you allow it.

Source: https://layerv.ai/for-agents/private-localhost-access-for-ai-agents/

---

[← For agents](https://layerv.ai/for-agents/) 

# Private localhost access for AI agents

## How can one agent give another agent private access to a local app without an email sign-in?

With qURL™, the recipient agent runs the qURL CLI, prints its device public key with qurl whoami -o json, and sends it to the owner, who adds it with qurl grants <CRID> --add <KEY>. The recipient then fetches the app with qurl get, or mints its own browser link with qurl share. No mailbox or account is involved. A recipient with only a browser needs a link instead.

**Checked against the qURL CLI source of 3.6.1 and 3.7.1.** The commands and JSON fields were read in the CLI source of both releases. “Resource Not Found (HTTP 404)” on a device that is not on the list was reproduced with both. Two recipients opening their own links in their own browsers was not run for this page. Verified November 8, 2026.

## Choose how the recipient gets in

Decide by what the recipient runs, before you publish. Each way in hands over something different. Taking the email path for a recipient that is a machine is how a task that needs no mailbox ends up waiting on one.

__Ways to let a recipient into a private qURL resource__
| Recipient                                  | It needs                            | What changes hands                                    | The owner runs                              |
| ------------------------------------------ | ----------------------------------- | ----------------------------------------------------- | ------------------------------------------- |
| Another agent or machine with the qURL CLI | The CLI and its own state directory | Its device public key, sent to the owner              | qurl grants <CRID> --add <KEY>              |
| A browser agent with no CLI                | A browser that keeps its session    | A one-time access link, sent to the agent             | qurl share <CRID> --ttl 1h                  |
| A person                                   | An email address and a browser      | An email invitation; they verify in their own browser | qurl access invite <CRID> --email <ADDRESS> |

## Who runs what

The owner is the machine, and the qurl state directory, that published the app. The recipient has its own state directory, on its own machine or in its own container. They never share one: a state directory is a device identity.

Every qurl command acts as the identity in the state it runs with. qurl share on the owner mints a link as the owner; on the recipient it mints one as the recipient’s device, and works only after the owner allowed that device. Each step below says where it runs.

## Give another agent access

1. ### On the recipient: print its device public key  
The key is device\_public\_key\_b64\. Send this public key to the owner through a channel that verifies the recipient’s identity. The owner must check who sent the key before granting access. On a new state directory this first command creates the device identity and prints “Using a new device identity.” on stderr. Keep that state directory for as long as the recipient needs access; a new one is a new identity with a new key.  
```  
qurl whoami -o json | jq -er '.device_public_key_b64'
```
2. ### On the owner: allow the key  
For an app you have not published yet, name the key when you publish, once per key. For one that is already published, add it with qurl grants: publishing the same address again returns the existing resource and keeps its list, and a publish that names another list fails with exit code 7\. Each --add changes one entry and leaves the others. In a container with no user service manager, publish with --foreground as the headless recipe shows.  
[An ngrok alternative for headless AI agents](https://layerv.ai/for-agents/ngrok-alternative-for-headless-agents/) →  
```  
# an app not yet published:
qurl publish http://127.0.0.1:3000 --allow-device-key "$KEY" -o json
# an app already published:
qurl grants "$CRID" --add "$KEY" -o json
```
3. ### On the owner: check the list  
Read authorization from qurl grants. status and inspect describe serving and say nothing about who may open the resource. This exits 0 only when the resource is private and the key is on its list.  
```  
qurl grants "$CRID" -o json |
  jq -e --arg k "$KEY" '.private == true and any(.allowed_device_keys[]; . == $k)' >/dev/null &&
  echo "allowed"
```
4. ### On the owner: send the CRID  
Send the recipient the CRID. The CRID of a private resource opens nothing by itself, so it is safe to send; no link has to change hands for a CLI recipient.
5. ### On the recipient: use the app  
qurl get fetches one response from the app’s root as the recipient’s device: use it for an API or a page to read. To use the app in a browser, the recipient mints its own one-time link and opens it in a browser it controls. The browser does not take on the CLI’s device identity, even on the same computer: it gets in through the link, and its session then belongs to that browser.  
```  
qurl get "$CRID" --file -
# or, for a browser on the recipient's side:
link=$(qurl share "$CRID" --ttl 15m -o json | jq -er 'select(.single_use == true) | .qurl')
```

## What a device that is not on the list sees

On any other device, qurl share <CRID> fails with exit code 5 and “Resource Not Found (HTTP 404)”, and qurl get fails with exit code 5 too. The answer is not found rather than forbidden: a private resource does not confirm to a stranger that it exists. Retrying does not change it.

To check the boundary yourself, run that command from a third, independent state directory that was never allowed. It shows that the service refuses a device that is not on the list. It does not show that a browser session is isolated; the verification page covers that separately.

## End access

Taking a key off the list, stopping the share and deleting the resource are three different things. qurl grants <CRID> --remove <KEY> takes one device off: from then on it cannot fetch the app or mint a link. This page does not establish whether a browser session that device already opened ends at that moment. Sessions expire after 1 hour by default. To make the app unreachable immediately, stop the share.

qurl stop <CRID> takes the local share offline for everyone and keeps the CRID and its list; qurl start brings it back. For a --foreground publish, ending that process does the same. qurl delete <CRID> --yes retires the CRID for good: ask the user first, and confirm it with the check on the JSON reference page.

```
qurl grants "$CRID" --remove "$KEY" -o json   # one device off the list
qurl stop "$CRID"                               # offline for everyone, CRID kept
qurl delete "$CRID" --yes -o json               # permanent: ask the user first
```

## Other ways to give a machine private access

Two other tools are often suggested for this task. They solve it with a different kind of credential and a different setup.

__qURL device keys, Cloudflare Access service tokens and Tailscale Serve__
| Aspect                     | qURL device keys                                                                 | Cloudflare Access service token                                                                       | Tailscale Serve                                                   |
| -------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Recipient setup            | Installs the qURL CLI; no account                                                | Sends two headers, CF-Access-Client-Id and CF-Access-Client-Secret; no software                       | Joins the tailnet, or accepts a share of the device               |
| Owner setup                | None; a device with no account keeps up to 3 active resources                    | A Zero Trust organization, an Access application on a domain in Cloudflare, and a Service Auth policy | A tailnet with HTTPS certificates enabled                         |
| Secret the recipient holds | Its own private key, which never leaves its machine; only the public key is sent | A client secret the owner creates and has to send to it                                               | Its tailnet node key                                              |
| Scope                      | One resource                                                                     | The Access applications whose policies include the token                                              | What the tailnet’s access rules let that device reach             |
| Lifetime                   | Until the key is removed or the resource deleted                                 | A duration the owner picks, 1 year by default, or no expiry                                           | As long as the device stays in the tailnet and the rules allow it |

## When another tool fits better

Cloudflare Access fits when the app is already behind Cloudflare on a domain and the recipient is a service that can send two headers on every request. Tailscale Serve fits when both machines are already in one tailnet: nothing new has to be set up at all. qURL device keys fit two machines that share neither, for one app, with nothing to set up beyond the CLI on each.

## Frequently Asked Questions

Does the recipient need a mailbox or a LayerV account? 

No. The device key path uses no email at any step, and neither side needs an account. The recipient’s first qurl command creates its device identity; linking an account later is optional.

Does a browser automatically inherit the CLI’s device identity? 

No. A browser is a separate client, even on the same computer. It gets in only through a link, which the allowed device mints with qurl share, and the session it starts belongs to that browser.

Can two recipients use the same one-time link? 

No. A one-time link starts one session, for the browser that opens it first. Give each recipient its own link: an allowed device mints its own with qurl share <CRID>.

Does publishing the same target again update its allowed devices? 

No. Publishing the same address again returns the existing resource with the list it has. A publish that names a different list with --allow-device-key fails with exit code 7\. Change the list with qurl grants <CRID> --add <KEY> or --remove <KEY>.

How is this different from Cloudflare Access service tokens? 

A service token is a client ID and secret that the owner creates in Cloudflare and has to send to the recipient, for an app already behind Cloudflare Access on a domain. With a qURL device key the recipient keeps its private key, the owner only ever receives the public key, and no domain or Cloudflare account is involved.

## Sources

Other tools are described from their own documentation.

- [Cloudflare docs: service tokens](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/) ↗
- [Cloudflare docs: add a self-hosted public application](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/) ↗
- [Cloudflare API: create a service token (duration)](https://developers.cloudflare.com/api/resources/zero%5Ftrust/subresources/access/subresources/service%5Ftokens/methods/create/) ↗
- [Tailscale docs: Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve) ↗

## Related Resources

[qURL CLI JSON reference for automation →](https://layerv.ai/for-agents/qurl-cli-json-for-automation/) [Verify private access for browser agents →](https://layerv.ai/for-agents/verify-private-preview-access/) [An ngrok alternative for headless AI agents →](https://layerv.ai/for-agents/ngrok-alternative-for-headless-agents/) [Guide: Give an AI agent access to a local app →](https://layerv.ai/guides/give-an-ai-agent-access-to-a-local-app/) [qURL vs Cloudflare Tunnel with Access →](https://layerv.ai/compare/qurl-vs-cloudflare-tunnel-access/) [qURL vs Tailscale Serve →](https://layerv.ai/compare/qurl-vs-tailscale-serve/) [The qURL skill →](https://layerv.ai/skills/qurl/SKILL.md)

## Give your agent the qURL skill

One file teaches a coding agent to publish an app privately, let people and other agents in, and recover when the CLI stops it. No account, no API key.

[Read the skill →](https://layerv.ai/skills/qurl/SKILL.md)



---

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

