Connect a folder
A machine needs somewhere to work. Connect the folder holding your repositories, and Norn records what is in it so an issue can be delegated to an agent that has somewhere to run.
Nothing about your folder is restructured. The root does not have to be a repository, and one folder can hold several.
Connect it
On the machine, from inside the folder:
cd ~/projects/acme
norn runner inspect
The scan prints what it found and asks you to confirm. Accept it and Norn records the inventory.
acme /Users/rae/projects/acme
├─ api main github.com/acme/api
├─ tooling main github.com/acme/tooling
└─ web main github.com/acme/web
shared AGENTS.md, Makefile, docker-compose.yml
tools claude 2.0.1, codex 0.9.4
runtimes process, docker
previews this machine can reach norn's preview gateway
connect this folder as "acme"? [y/N]
Answer y and it prints connected acme to https://app.norn.so with 3 repositories.
Use --confirm to accept without being asked. With no terminal and no --confirm, the runner
refuses rather than assuming.
The folder appears under Workspace settings → Runners, beneath the machine holding it.
What the scan reads
| It records | What that means |
|---|---|
| Repositories | Every git repository under the root, with its name, path and default branch |
| Remotes | A fingerprint of each remote — a hash, the host and the tail of the path. The full URL never leaves the machine |
| Shared files | Instruction and configuration files at the root: AGENTS.md, CLAUDE.md, README.md, docker-compose.yml, Makefile, Taskfile.yml, justfile, mise.toml, flake.nix, devcontainer.json |
| Runtimes | Whether the machine can run work as processes, in Docker, or on KVM |
| Coding agents | claude and codex, with the versions found |
It descends five levels by default and never follows a symlink out of the root. It does not enter package or build caches.
Nothing in the folder is written. Only read-only git plumbing runs, so the folder is byte-identical afterwards.
How repositories are classified
| Case | What happens |
|---|---|
| An ordinary repository | Listed |
| A linked worktree | Listed |
| A repository nested inside another, not a submodule | Listed on its own, and excluded from its parent |
| A submodule | Recorded as part of its parent, not on its own |
| A bare repository | Ignored, with a warning |
When the repositories change
The machine re-scans when it starts and every six hours. If it finds a different set of
repositories from the one you confirmed, the folder moves into drift — in
norn runner status and on the runners screen.
Drift blocks nothing. Runs carry on against the repositories they already know. It means only that a person has not yet agreed to the change.
Norn cannot clear it for you, because only the machine can see the folder. Re-confirm there:
cd ~/projects/acme
norn runner inspect
The scan lists what was added, removed or changed and asks accept this folder as it now stands?.
--confirm accepts without asking. When nothing has moved it prints
nothing has changed since this folder was confirmed and does nothing.
One case clears itself: if a re-scan finds exactly the set you already confirmed, the machine confirms it without asking.
A folder whose root has been deleted is logged and left alone. It is never disconnected for you.
Connect a second folder
Run norn runner inspect in the other folder. One machine holds as many folders as you connect.
Two folders may not overlap, in either direction, and a folder holding no repositories is refused.
The same folder connected by two machines is two separate records, which is correct — they are two computers.
Disconnect a folder
Open Workspace settings → Runners, find the folder and use Disconnect this folder.
Disconnecting is a state, not a deletion. Runs that already named the folder keep resolving, so history stays readable. Re-connecting the same path afterwards creates a new record.