In development, a harness's code and its work share one folder: the project. An installed application cannot work that way — its own files are read-only — and a server may want one build serving several data folders. So where a run's work lives is one setting, separate from where the code is.
When to use it
- Run the same build against more than one data folder — a test set, a customer's corpus, a clean slate.
- Serve from a box where the code is read-only and the work must go to a writable volume.
- Understand where an installed desktop app keeps its models and settings — it uses this same rule.
Set it
LLOYAL_PROJECT_ROOT=/srv/field-notes npm startWhere the work lives is decided in this order, first one that says something:
- A
projectRootpassed to the boot in code LLOYAL_PROJECT_ROOTin the environment- The working directory — the project, when you run from it
A blank value counts as not set (never the root of the filesystem), and the result is always made absolute. Both boots — the terminal and desktop one, and the served host — read it.
It belongs in the environment rather than in harness.yml for the same reason PORT and MAX_SESSIONS do: it describes the machine, not the harness.
What moves
| Lives in the data root | Stays with the code |
|---|---|
harness.yml — the manifest that run reads |
The compiled program and its dependencies |
harness.json — settings saved from the pane |
The prompt folder, src/harness/prompts/ |
models/ — the downloaded weights |
|
media/ — the content store for attachments |
|
sources.outputDir — what the harness keeps, and the trace, when it is a relative path |
The data root must contain a harness.yml: it is the manifest the run reads. Copy the project's to start one.
The desktop app uses the same rule
An installed desktop app has two places because the operating system allows no other way: its own files ship inside the application bundle, read-only, and everything a run produces goes to a writable folder the platform gives each installation. The shell points the engine's data root there, and copies the shipped harness.yml into it once, on first launch — after that the file is the installation's own, and an update never rewrites it. Ship a desktop app has the details.
Related
- Serve to many users — the served host reads the same setting.
- harness.yml — the manifest, and the box's own settings.