Skip to main content
← For agents

Headless qURL: native or external supervision?

Does running qURL in Docker or CI require external supervision or anonymous login?

No. In Docker, CI or any headless shell, qURL™ uses native supervision: run qurl publish with --foreground as a background job, and the first command creates a device identity with no login. External supervision is for an application that runs the qURL daemon itself and seals the state with a key it holds. It needs its own empty state directory and enrollment; an existing native state cannot be switched to it.

Checked against the qURL CLI source of 3.7.1. The three error texts were reproduced with CLI 3.6.1 and 3.7.1. The external contract was read in the 3.7.1 help text and source; no external enrollment was run for this page. Verified .

Three things that are easy to mix up

Owning a process’s lifetime is not external supervision. A test harness that starts the publisher and stops it afterwards is running native qurl in the foreground.

Native supervision, --foreground and external supervision
TermWhat it isWho needs it
Native supervisionThe default. qurl runs its own daemon: a per-user background service, or the publish process itself with --foregroundEvery ordinary use, containers and CI included
--foregroundServe from the publish process instead of a background service; the share stops when that process exitsA container or CI job with no user service manager
External supervisionAnother application starts qurl daemon run itself, owns its lifetime, and seals the state with a wrapping key it holdsAn application that embeds qURL and manages that key

The headless path is native

Install the CLI, run qurl publish <target> --foreground as a background job, wait for serving, and stop the process when you are done. No qurl login runs at any point, and no key provider is set: the first command on an empty state directory creates the device identity and prints “Using a new device identity.”. The container guide and the headless recipe have the commands.

An existing state directory keeps its mode

A state directory is created for one mode and stays in it. Adding --supervision external to any command on native state fails with exit code 3. It is a configuration error, not a step to complete: drop the flag.

The message names a login. Following it on its own fails again, with exit code 2, because external enrollment also needs a sealed key provider. Unless you are building that supervisor, don’t log in at all.

Output: qurl --supervision external, on native state (exit code 3)
Error: runtime supervision is "native", not "external"; enroll a dedicated empty state directory first with qurl login --anonymous --supervision external or qurl login --enrollment-token-file <path> --supervision external

As printed in recorded runs of qURL CLI 3.6.1 and 3.7.1; see #runtime-supervision-native in the error reference.

What the anonymous login asks for

qurl login --anonymous --supervision external without a sealed key provider stops before it enrolls anything. Switching a native state directory to external is never a migration: an external identity needs a dedicated, empty directory, and the native identity and its resources stay where they were.

Output: qurl login --anonymous --supervision external (exit code 2)
Error: --anonymous requires LAYERV_KEY_PROVIDER=local-key

As printed in recorded runs of qURL CLI 3.6.1 and 3.7.1; see #anonymous-requires-local-key in the error reference.

What external supervision requires

All of these, together, from the CLI’s help and source: a dedicated, empty state directory; enrollment with qurl login --anonymous --supervision external for an account-free device, or --enrollment-token-file <path> --supervision external with a one-time token that a signed-in supervisor minted; LAYERV_KEY_PROVIDER=local-key on every command; and the wrapping key passed on an inherited file descriptor whose number is in LAYERV_LOCAL_KEY_FD. QURL_DAEMON_SUPERVISION=external is the environment form of the flag.

Every later command must run with the same directory, the same mode and the same wrapping key: an existing external identity is reopened, never replaced. The key travels only on the descriptor. Never put it in a command argument, an environment value, a log or a chat message. The anonymous enrollment refuses account key configuration, so leave QURL_API_KEY unset.

This page has no complete external example yet. The key format, the descriptor’s lifetime and a warm reopen were read in the source, not run, and a recipe is complete only when enrollment, a reopen, an operation and cleanup all work under the same identity. Build against qurl login --help for the release you ship.

A writable directory is not a credential directory

Whatever the mode, qurl exits with code 3 if a parent directory is writable by other users and lacks the sticky bit. This often follows a chmod 777 that made a mounted workspace writable for the container’s user. Keep the two apart: the workspace can be as open as the app needs, and the state directory belongs to the container user with mode 0700. A new Docker volume belongs to root. Before the first qurl command, change its owner to the user and group that run qurl in your image. The example uses UID 1000 and GID 1000.

Output: Any qurl command, with state under a 0777 home (exit code 3)
Error: Other users can write to /home/node (mode 0777), so qURL can't safely keep its files under it.

  Hint: run `chmod go-w /home/node`, then retry. Or set QURL_CONNECTOR_STATE_DIR (or XDG_STATE_HOME) to a directory you own that other users can't write to.

As printed in recorded runs of qURL CLI 3.6.1 and 3.7.1; see #other-users-can-write in the error reference.

docker volume create qurl-state
docker run --rm --user root -v qurl-state:/qurl-state <image> \
  sh -c "chown 1000:1000 /qurl-state && chmod 700 /qurl-state"
docker run --user 1000:1000 -v qurl-state:/qurl-state -e QURL_CONNECTOR_STATE_DIR=/qurl-state <image>

Frequently Asked Questions

Do I need qurl login in CI or Docker?

No. The first qurl command on an empty state directory creates a device identity with no account and no login. qurl login is for linking an account key, or for an external supervisor’s enrollment.

Can I convert native state to external supervision?

No. External enrollment needs a dedicated, empty state directory, and it creates a new identity there. The native identity keeps its own resources, and only it can delete them.

What is LAYERV_LOCAL_KEY_FD?

The number of an open file descriptor, inherited from the supervising process, that carries the wrapping key for sealed state under LAYERV_KEY_PROVIDER=local-key. The key itself never goes in a variable or an argument.

Does --foreground mean external supervision?

No. --foreground is native: the publish process runs the daemon itself and stops the share when it exits. External supervision is a separate state mode with its own enrollment.

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.