Skip to main content
← For agents

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.

qURL, ngrok and Cloudflare Quick Tunnels for a headless agent
AspectqURLngrokCloudflare Quick Tunnel
AccountNone; the first command creates a device identityRequired: the agent needs an authtoken from an ngrok accountNone
Credential to configureNoneThe authtoken, with ngrok config add-authtoken, NGROK_AUTHTOKEN or --authtokenNone
What a recipient getsNo public URL: a one-time link, or access for an allowed device keyA public URL; Traffic Policy can add OAuth, OIDC, basic auth or IP rulesA public trycloudflare.com URL; --allowed-mail adds an email PIN that needs an interactive browser
LifetimeServed while the publish process runs; the CRID lasts until deletedAn agent endpoint is online while the agent process runsWhile cloudflared runs, with a new hostname each time
LimitsWithout an account, up to 3 active resources, with links that last up to 24 hoursFree plan: a warning page in front of HTML browser trafficFor 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

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

    Guide: Share an app from a container or CI →

  2. 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
    fi
  3. Confirm 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"
  4. 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')
  5. 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
fi

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

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.