Steps
With qURL™, publish your local app with qurl publish and give the cloud agent a link from qurl share --ttl 1h to open in its browser. Keep that browser session open for the test. The agent uses the running app through qURL, with nothing to deploy.
Check where the agent’s browser runs
A browser that runs on your machine reaches localhost already, and needs no link. Claude in Chrome drives your own Chrome; Playwright MCP launches a browser locally; Browserbase’s browse CLI uses a local browser with --local; and OpenAI points to the ChatGPT desktop app’s built-in browser for localhost. A cloud browser is different. OpenAI says ChatGPT’s cloud browser runs “on a separate computer in the cloud, not the browser on your phone or laptop”, and a Browserbase session runs in its own remote sandbox. The rest of this guide is for those.
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 --versionPublish the app
Replace 3000 with your app’s port. The first publish creates this device’s identity, starts a background service that keeps serving after you close the terminal (while you stay logged in), and prints the app’s CRID, its stable ID. The Access row says who can open the app: a plain publish makes it private from qurl 3.4.1 on.
qurl shareturns the CRID into an access link, and the link is what you send. The link reaches the app, not past its login, so give the agent a test account rather than yours.qurl publish http://127.0.0.1:3000Keep the same browser session for the test
A qURL browser session belongs to the browser that opened the link. Keep that browser’s profile and cookies for the whole task; if the agent starts a new browser or clears its state, send a new link. Proxy settings are separate: Browser Use Cloud enables a US residential proxy by default, and proxyCountryCode: null disables its managed proxy. Turning proxies off does not replace keeping the browser session.
Create a short-lived link
The link opens once. --ttl ends it if the agent never gets to it; the session it opens lasts 1 hour by default, and --session-duration changes that.
qurl share <CRID> --ttl 1hGive the agent the link, and tell it to open it in the browser
Put the link in the task. It is a secret: whoever opens it first uses it, so don’t open it yourself to check it. The agent must open it in its browser. A fetch or HTTP tool gets the opener page instead of your app, because the credential is in the part of the URL after #, which HTTP clients never send.
Open this link in your browser; don't fetch it: <link> Sign in with the test account, then <the test you want run>.End access when the test is done
qurl stoppauses serving the app;qurl startresumes it. The session also ends on its own when it runs out.qurl stop <CRID>
What the recipient sees
The agent’s browser lands on your app at an address like https://r_….qurl.site/, with no warning page or sign-up, and works through it as a person would.
More
WebSockets and Server-Sent Events pass through, so live updates and streamed replies reach it. Another browser on the same public IP cannot use that browser’s access. Keep your app’s own login on and use a test account.
Troubleshooting
| If you see | Do this |
|---|---|
| The agent reports a page titled “qURL - Private Links That Expire” instead of the app | It fetched the link with an HTTP tool rather than opening it in its browser. Make a new link with qurl share and tell the agent to open it in the browser. |
| The agent reaches the app, then loses it partway through the task | Check whether the agent replaced its browser, cleared its cookies, or let the session expire. Keep the same browser profile throughout the task; send a new link if it starts a new browser. Investigate proxy or network failures separately. |
Show 8 more fixes
| If you see | Do this |
|---|---|
| The agent’s very first open says the link was already used | A browser-capable scanner, you, or an earlier browser tool call may have opened it first. A plain HTTP preview cannot use the secret after #. Send a new link, and don’t open it yourself. |
| The app answers “Blocked request”, “Invalid Host header” or a similar host error | Your dev server rejects qURL’s hostname. The guide to allowing a tunnel’s hostname lists the setting for each 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
Why can’t the cloud browser just open localhost?
localhost means the machine the browser runs on. A cloud browser runs on someone else’s computer, so its localhost is not yours. OpenAI says its cloud browser runs “on a separate computer in the cloud, not the browser on your phone or laptop”.
Can the agent open the link without a browser?
Not with curl or a fetch tool: those return the opener page. In code, the qURL Go SDK opens a link without a browser; the guide to giving an AI agent access to a local app shows how.
Who else can reach my app while the link is open?
Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. 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.
How do I stop sharing?
Run qurl stop <CRID> to pause serving the app, and qurl start <CRID> to resume it; a stopped app still counts toward your resource limit. qurl delete <CRID> removes the resource for good after asking you to confirm; its CRID can never be shared again.