norn runner reference

Commands you run on the machine. They need no credentials of their own — the runner holds the machine's identity, and these talk to it over a local socket.

Binding

norn runner connect

Bind this machine to a Norn agent.

Flag	What it does
--token	The agent's API token, read once and discarded. NORN_TOKEN is read when this is absent, and is the safer way to pass one — an argument is visible to anything that can read ps.
--name	What to call this machine in Norn. Defaults to the hostname.
--force	Replace an existing binding on this machine.
--insecure-store	Keep credentials in a file encrypted with the machine id, for hosts with no OS keystore.

The runner must already be running. connect with no daemon listening exits 4 and says so.

norn runner disconnect

Unbind this machine and clear its credentials. It does not remove the machine from Norn — see Revoke a machine.

Folders

norn runner inspect

Read the current folder and connect it to Norn. Run again after the repositories change to clear drift.

Flag	What it does
--confirm	Accept what the scan finds without asking.
--json	Write the scan as JSON.

Running

norn runner start

Run the runner in the foreground.

Flag	What it does
--capacity	How many executions may run at once.
--runtime	auto, process or docker.

norn runner install

Register the runner with this machine's service manager, so it starts on boot — launchd on macOS, systemd on Linux.

norn runner uninstall

Take it back out again.

norn runner pause · norn runner resume

Stop taking new work on this machine, and start again. What is already running carries on either way. Pausing survives a restart.

Both take --json.

Reading

norn runner status

Say whether the runner is running and what it is bound to — its agent, slots, folders, and whether the channel and previews are up. Takes --json.

norn runner executions

List the runs this machine has taken. Takes --json.

norn runner logs <exec>

Show what happened in one run. Takes --json.

norn runner version

Say which build this is and whether a newer one has been released.

Flag	What it does
--json	Write the report as JSON.
--no-check	Do not ask whether a newer release exists.

Snapshots

A run copies the connected folder into a scratch workspace before touching anything. These commands are for looking at what is being held, and for clearing it up by hand if something went wrong.

norn runner snapshot list

List the snapshots this machine is holding.

norn runner snapshot remove <name>

Take a snapshot away and give the original repositories their worktrees back.

norn runner snapshot take <ISSUE-KEY>

Take a copy of the current folder for an issue, leaving the original untouched.

Flag	What it does
--codebase	A path inside the connected folder to copy.
--attempt	Which attempt at this issue this is.
--include-dirty	Include uncommitted changes.

Configuration

~/.norn/runner.yaml. The settings worth knowing:

version: 1
server: https://app.norn.so
capacity: 2                 # parallel executions
runtime: auto               # auto | process | docker
retention:
  workspace_after_done: 30m
  runs_max_age: 14d
  runs_max_disk: 20GB
telemetry: standard         # standard | minimal

telemetry: minimal sends summaries instead of full transcripts. NORN_STATE_ROOT relocates ~/.norn and everything under it.

Commands a run uses

norn preview, norn service, norn ask and norn mcp-server belong to a run, not to you. They read the run's id and token from the environment of that run's own processes, so the coding agent working through a shell has them and a person at a terminal does not.

Everything they do is on the run screen: previews, services and questions.