Skip to main content
← All guides

Let a cloud browser agent test your local app

Why qURL here

Give a cloud browser agent an access link to the app running on your machine, without deploying a copy. The agent must open the link in its browser, then test the running app there.

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.

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

  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. Publish 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 share turns 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:3000
  4. Keep 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.

  5. End access when the test is done

    qurl stop pauses serving the app; qurl start resumes 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

Troubleshooting
If you seeDo this
The agent reports a page titled “qURL - Private Links That Expire” instead of the appIt 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 taskCheck 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
More troubleshooting
If you seeDo this
The agent’s very first open says the link was already usedA 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 errorYour 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 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

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.

Publish your app now

Install the CLI, then run one command. No sign-up, no API key.

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