One file at the project root. Every command finds it by walking up from the working directory, the same way git finds .git.

protect:  # paths relative to this file
 - .env            # a file
 - config          # a directory, and everything under it
 - config/**       # the same thing, spelled out
 - src/*.ts        # * stops at /
 - "**/secrets.json" # ** does not

• agent.lock always protects itself, whether or not you list it.
• .., absolute paths, ~ and ! negation are rejected at parse time rather than quietly reinterpreted. A policy that does not mean what it says is worse than no policy.
• Unknown keys are errors, so protects: fails loudly instead of parsing as a policy that happens to protect nothing.
• version: is optional and means 1. Files that state it still work and version: 2 is still refused — it just was not earning its line, since "no version stated" says version one perfectly well and always will.
• An empty agent.lock is refused rather than treated as a policy with nothing in it. "Enforced, protecting nothing" is the one status that must never be reassuring, and touch agent.lock is an easy way to reach it.

Matching is case-sensitive on Linux and case-insensitive on Windows and macOS. On a case-insensitive filesystem, a deny list that matched fewer paths than the filesystem does would be wrong in the dangerous direction.

Every command takes --dir to point at a project other than the working directory. Supervisor state — the scopes, the recorded workspaces, the log, and Ralon's own copy of the binary — lives in %LOCALAPPDATA%\Ralon or ~/Library/Application Support/Ralon, relocatable with RALON_HOME.

The copy is why install registers a path of its own rather than wherever the executable happened to be. Most installs put that inside a package manager's directory, and Windows will not delete the image of a running process — so a supervisor running from node_modules made its own package impossible to uninstall, with an error about permissions rather than about a running process.

These are the interface. A wrapper that swallows them reports every policy as satisfied.

Otherwise run exits with your command's own status, because it is your command by then.

run picks the strongest backend the kernel offers. ralon status shows what is available and --backend pins it.

The first three are inherited — applied to a process before it starts and impossible to impose on one already running, which is why run exists and why Linux has no supervisor. The last two are imposed — held by one process and refused to everybody else — which is why a guard can protect agents it did not start.

mount — the default

Read-only bind mounts inside a user and mount namespace, locked by entering a second namespace so they cannot be undone. Every parent directory of a protected path becomes a mount point too, so no directory on the way to it can be renamed or removed. Precise: nothing outside the protected paths behaves differently. Needs unprivileged user namespaces, which some hardened distributions and container runtimes disable.

landlock — the fallback

The kernel LSM, Linux 5.13+. Needs no namespaces, so it works exactly where the mount backend cannot. Landlock rules are additive — a rule may grant more access than its parents, never less — so "everything except this file" has to be expressed by granting every sibling along the way instead.

seatbelt — macOS, under run

The policy compiled to SBPL and applied with sandbox_init before the command starts. The only mechanism here that can say deny outright, so it needs no carve-out and no ACL: a protected directory covers whatever is created in it later, and ancestors are denied as literal nodes so none of them can be renamed while staying writable inside.

immutable — macOS, under the supervisor

chflags uchg on each protected path. It is the only way to impose a restriction on a process you did not start without asking for root, and it is honestly weaker than the other four: an agent undoes it with chflags nouchg, and it cannot pin an ancestor without also freezing it, so renaming an unprotected parent directory moves the path out from under the policy. ralon run has neither limitation, and ralon status warns when a policy has an ancestor exposed this way.

locks — Windows

Exclusive share-mode handles on every protected path, held for as long as Ralon holds them and refused to every process on the machine — no cooperation required from the thing being refused. Directories are narrowed with an ACL as well, because a handle on a directory does not stop files being created inside it. The handles are a property of the file object rather than of a session, so a guard started by the supervisor in the background is refusing writes from your terminal too.