# Headless qURL: native or external supervision?

> Running qURL in Docker or CI needs no login and no external supervision. When --supervision external applies, and what its sealed state requires.

Source: https://layerv.ai/for-agents/headless-native-vs-external-supervision/

---

[← For agents](https://layerv.ai/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 November 8, 2026.

## 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__
| Term                 | What it is                                                                                                             | Who needs it                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Native supervision   | The default. qurl runs its own daemon: a per-user background service, or the publish process itself with --foreground  | Every ordinary use, containers and CI included       |
| \--foreground        | Serve from the publish process instead of a background service; the share stops when that process exits                | A container or CI job with no user service manager   |
| External supervision | Another application starts qurl daemon run itself, owns its lifetime, and seals the state with a wrapping key it holds | An 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)`

```text
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)`

```text
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)`

```text
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.

## Related Resources

[An ngrok alternative for headless AI agents →](https://layerv.ai/for-agents/ngrok-alternative-for-headless-agents/) [Guide: Share an app from a container or CI →](https://layerv.ai/guides/share-from-a-container-or-ci/) [Error: runtime supervision is "native", not "external" →](https://layerv.ai/for-agents/qurl-cli-errors/#runtime-supervision-native) [Error: --anonymous requires LAYERV\_KEY\_PROVIDER=local-key →](https://layerv.ai/for-agents/qurl-cli-errors/#anonymous-requires-local-key) [Error: Other users can write to … so qURL can’t safely keep its files →](https://layerv.ai/for-agents/qurl-cli-errors/#other-users-can-write) [Fix socket chmod invalid argument in Docker Desktop →](https://layerv.ai/for-agents/fix-docker-desktop-socket-chmod-invalid-argument/) [The qURL skill →](https://layerv.ai/skills/qurl/SKILL.md)

## 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 →](https://layerv.ai/skills/qurl/SKILL.md)



---

*This markdown version is auto-generated from [https://layerv.ai/for-agents/headless-native-vs-external-supervision/](https://layerv.ai/for-agents/headless-native-vs-external-supervision/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

