An ngrok alternative for headless AI agents
How can a headless coding agent share a private local app without configuring an ngrok authtoken?
Install the qURL™ CLI where the app runs, run qurl publish with --foreground as a background job, and wait until qurl status reports serving. The resource is private: let a recipient in with a device key or a one-time link. No account or authtoken is configured, but the first command creates a device identity on disk that must be kept until cleanup. The share lasts while that process runs.
Checked against the qURL CLI source of 3.7.1. Reviewed against the CLI source and the container guide, whose foreground publish was run on a clean Linux container. The failure and cleanup answers were reproduced with 3.6.1 and 3.7.1. These steps as written were not run end to end. Verified .
When this fits
It fits a private, temporary preview shared from a shell the agent controls: Claude Code, Codex, Cursor, OpenCode, or any agent that runs commands on the machine or in the container where the app runs. These agents are named for the shell they give an agent; this page was not run in each of them.
It needs four things: shell access where the app runs, the app listening on a loopback address, a state directory that the agent’s user owns and other users cannot write to, and a process that stays alive for as long as the share should. It does not fit a public URL for anyone, such as a webhook sender’s callback: a qURL resource is private unless it is published with --public.
What each tool asks of an unattended agent
ngrok has real coding-agent support: a setup prompt that installs ngrok and keeps the authtoken out of the chat, a skill, and an MCP server. The MCP server signs in with OAuth or a personal access token, a different credential from the agent’s authtoken; ngrok says authtokens don’t work with it. For a headless run, the difference is the first step: someone with an ngrok account has to provide that authtoken. A Cloudflare Quick Tunnel needs no account either, and gives a public URL instead.
| Aspect | qURL | ngrok | Cloudflare Quick Tunnel |
|---|---|---|---|
| Account | None; the first command creates a device identity | Required: the agent needs an authtoken from an ngrok account | None |
| Credential to configure | None | The authtoken, with ngrok config add-authtoken, NGROK_AUTHTOKEN or --authtoken | None |
| What a recipient gets | No public URL: a one-time link, or access for an allowed device key | A public URL; Traffic Policy can add OAuth, OIDC, basic auth or IP rules | A public trycloudflare.com URL; --allowed-mail adds an email PIN that needs an interactive browser |
| Lifetime | Served while the publish process runs; the CRID lasts until deleted | An agent endpoint is online while the agent process runs | While cloudflared runs, with a new hostname each time |
| Limits | Without an account, up to 3 active resources, with links that last up to 24 hours | Free plan: a warning page in front of HTML browser traffic | For testing: 200 in-flight requests, no Server-Sent Events |
Check before you publish
Check the app on the exact address you will publish: a dev server that listens only on IPv6, as Vite often does on macOS, is published as http://[::1]:<port>. Pin the CLI release so every run behaves the same.
qurl keeps a device identity, a credential, in its state directory: $HOME/.local/state/qurl by default. The CLI refuses a directory under a parent that other users can write to unless that parent has the sticky bit set, as /tmp usually does. A writable workspace and an acceptable credential directory are different things: keep the app’s files where they are, and give qurl a private directory of its own. Run preflight, publish and the steps below in the same shell. That shell holds the state path, CRID and background job. If your tool starts a fresh shell for every call, run the steps in one script.
On Docker Desktop for macOS with the home directory bind-mounted from the Mac, also move the daemon’s socket into the container, as the socket page explains.
curl -fsS -o /dev/null http://127.0.0.1:3000 || echo "nothing answers on 127.0.0.1:3000" >&2
qurl --version
QURL_CONNECTOR_STATE_DIR=$(mktemp -d) &&
export QURL_CONNECTOR_STATE_DIR &&
echo "qurl state: $QURL_CONNECTOR_STATE_DIR"Publish, wait, and hand over
Install the qURL CLI
Use the installer from the container guide, with VERSION set so every run gets the same release. It verifies the CLI against the release checksums and never runs sudo.
Publish in the foreground, as a background job
A plain publish installs a per-user background service and exits; a container or sandbox with no systemd user manager cannot run one, so serve from the publish process with --foreground. That flag alone does not keep the share alive past your tool call: some agent tools end background jobs when a command returns. nohup and the redirects detach it from the terminal; if your tool still ends it, run the rest of the steps in the same command. --foreground does not avoid the Docker Desktop socket error either. This waits up to 90 seconds for the publish document, which appears once the app is serving.
CRID="" if [ -n "$QURL_CONNECTOR_STATE_DIR" ] && run=$(mktemp -d); then nohup qurl publish http://127.0.0.1:3000 --foreground -o json \ > "$run/publish.json" 2> "$run/publish.log" < /dev/null & pub=$! for i in $(seq 1 90); do CRID=$(jq -er '.crid | strings | select(length > 0)' "$run/publish.json" 2>/dev/null) && break kill -0 "$pub" 2>/dev/null || { CRID=$(jq -er '.crid | strings | select(length > 0)' "$run/publish.json" 2>/dev/null); break; } sleep 1 done [ -n "$CRID" ] || { echo "publish failed:"; cat "$run/publish.log"; kill "$pub" 2>/dev/null; false; } else echo "Publisher state or temporary directory unavailable." >&2 false fiConfirm it is serving and private
A CRID proves that the resource exists, not that the app answers through it. Check both before you hand anything over: status for serving, grants for privacy. If either check fails, run qurl inspect "$CRID" -o json and read daemon_state and local_target_health.
qurl status "$CRID" -o json | jq -e '.desired_state == "on" and .connection_state == "serving"' >/dev/null && qurl grants "$CRID" -o json | jq -e '.private == true' >/dev/null && echo "serving, private"Let the recipient in
For another agent that runs the qURL CLI, allow its device key: no link changes hands. For a browser, mint one one-time link per recipient. Don’t open it to test it: opening uses its one opening.
Private localhost access for AI agents →
link=$(qurl share "$CRID" --ttl 1h -o json | jq -er 'select(.single_use == true) | .qurl')Hand over the result
Give your user the CRID, how to open it (the link opens in a browser and must not be fetched with curl), when the link expires, and that the share stops when the publish process ends. Give the link to your user, and send it on, or send invitations, only when the user asked you to.
Clean up, and what to do when publish fails
Stop the publish job in the shell that started it. This takes the app offline and keeps the resource, switched off, with its CRID. When the container or runner is about to be thrown away, delete the resource first, after asking the user, and confirm it: qurl share then fails with exit code 5 and “Resource Revoked (HTTP 400)”. Keep the state directory until that is confirmed: it holds the only identity that can delete the resource.
If the publish step failed, $CRID may be empty while the resource exists: a failure while starting the daemon or waiting to serve leaves it created and switched off. Don’t publish with a new state directory to start fresh; that is a second identity and a second resource. Reconcile first.
# Run in the publishing shell after the user approves deletion.
if [ -n "${CRID:-}" ] && [ -n "${QURL_CONNECTOR_STATE_DIR:-}" ]; then
qurl delete "$CRID" --yes -o json
else
echo "Missing CRID or publisher state. Recover the failed publish first." >&2
false
fiWhen another tool fits better
Keep ngrok when the agent already has an authtoken it is allowed to use, or the task needs what ngrok adds: Traffic Policy rules such as OAuth, OIDC, JWT validation or IP restrictions, or the free dev domain, which stays the same between runs. Use a public tunnel, ngrok or a Cloudflare Quick Tunnel, when anyone with the URL should reach the app, such as a webhook sender. Use Tailscale Serve when both machines are already in one tailnet.
Frequently Asked Questions
Does qURL need an authtoken or API key?
No. The first qurl command creates a device identity in the state directory, with no account. That identity is a credential on disk: keep the directory private, and don’t copy it into a CI cache or artifact.
Is a Cloudflare Quick Tunnel also account-free?
Yes. It needs no account or domain and gives a public trycloudflare.com URL that anyone with it can open. Its --allowed-mail option adds an email one-time PIN, which needs an interactive browser and does not support non-interactive clients, so another agent without a browser cannot get through it.
Why did the share stop when my agent’s command returned?
The share lasts as long as the --foreground publish process. Some agent tools end background jobs when a command returns. Start it with nohup and redirects, and if the tool still ends it, run the publish and every command that needs the share in one command.
Is the ngrok MCP server’s sign-in the same as an authtoken?
No. ngrok’s MCP server signs in with OAuth in a browser or a personal access token, and ngrok says API keys and authtokens don’t work with it. The ngrok agent that serves the endpoint uses the authtoken.
Was this tested in Claude Code, Codex, Cursor and OpenCode?
No. They are named for the shell they give an agent. The publish failures and their fixes were reproduced in Linux containers on Docker Desktop for macOS; these steps were reviewed against the CLI source.
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.