Skip to main content
← 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 .

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
RecipientIt needsWhat changes handsThe owner runs
Another agent or machine with the qURL CLIThe CLI and its own state directoryIts device public key, sent to the ownerqurl grants <CRID> --add <KEY>
A browser agent with no CLIA browser that keeps its sessionA one-time access link, sent to the agentqurl share <CRID> --ttl 1h
A personAn email address and a browserAn email invitation; they verify in their own browserqurl 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 →

    # 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
AspectqURL device keysCloudflare Access service tokenTailscale Serve
Recipient setupInstalls the qURL CLI; no accountSends two headers, CF-Access-Client-Id and CF-Access-Client-Secret; no softwareJoins the tailnet, or accepts a share of the device
Owner setupNone; a device with no account keeps up to 3 active resourcesA Zero Trust organization, an Access application on a domain in Cloudflare, and a Service Auth policyA tailnet with HTTPS certificates enabled
Secret the recipient holdsIts own private key, which never leaves its machine; only the public key is sentA client secret the owner creates and has to send to itIts tailnet node key
ScopeOne resourceThe Access applications whose policies include the tokenWhat the tailnet’s access rules let that device reach
LifetimeUntil the key is removed or the resource deletedA duration the owner picks, 1 year by default, or no expiryAs 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.

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 →

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.