Skip to main content

Connect a machine

A machine is a computer running the Norn Runner, bound to one agent. Work delegated to that agent runs there.

Run everything on this page on the computer you want the work to happen on — not on the machine you happen to be reading this on.

Register an agent​

A machine acts as an agent, so you need one first. Open Workspace settings → Agents and register it. Norn shows the agent's API token once, when you create it.

Agents page screenshot placeholder showing the register form and the token dialog

Copy that token. It is the same token that goes into an MCP config — there is no separate enrolment token to create.

If you no longer have it, open Workspace settings → Runners → Connect a machine and use Issue a new token. Issuing a new one stops the old one working, so anything already using it needs the new token too. Machines that are already connected are not affected.

Install and connect​

The installer detects the platform, verifies the download's checksum, installs the binary, registers the runner with your service manager, and connects it when you give it a token.

NORN_TOKEN=nrn_… curl -fsSL https://get.norn.so/runner | bash

NORN_TOKEN is the way to pass a token. --token also works, but the value is visible to anything that can read ps while the command runs.

Nothing else to set. The runner talks to https://app.norn.so.

Install without connecting​

To install the binary and bind it later:

curl -fsSL https://get.norn.so/runner | bash
norn runner connect --name "build-box"

--name is what the machine is called in Norn. It defaults to the hostname.

Homebrew works too:

brew install usenorn/norn/norn-runner
norn runner install
norn runner connect

Check it worked​

norn runner status

The machine appears under Workspace settings → Runners, grouped under the agent it acts as, within a few seconds of connecting.

Runners page screenshot placeholder showing a connected machine with its host, slots and last seen

A machine that has enrolled but never opened a connection reads Never connected. Start the runner on it:

norn runner start

norn runner install registers it with launchd or systemd so it starts on boot. The installer does this for you unless you passed --no-service.

What the machine keeps​

The token you pasted is read once and thrown away. It is never written to disk.

In exchange the machine generates its own keypair and receives a credential bound to that key. Both go into the operating system's keystore — Keychain on macOS, Secret Service on Linux. The private key never leaves the computer, and the credential is useless without it.

That is what makes revoking one machine possible without touching the agent's other machines or its MCP access.

note

A headless Linux host with no Secret Service can fall back to a file encrypted with the machine id, using norn runner connect --insecure-store. It is never chosen silently, and a host with no machine id is refused rather than handed a key the runner invented for itself.

Connect a second machine​

Repeat the same steps on the other computer with the same agent token. One agent can hold several machines — a laptop and a build box — and Norn offers work to whichever one has room.

Move a machine to a different agent​

norn runner connect --token nrn_… --force

--force replaces the binding on this machine. The old machine record stays in Norn until an administrator revokes it.

Disconnect​

norn runner disconnect

This clears the credentials and identity on the machine and stops it taking work. It does not remove the machine from Norn — a machine has no authority to revoke itself. To retire it for good, revoke it from the dashboard.

To remove the service and the binary as well:

curl -fsSL https://get.norn.so/runner | bash -s -- --uninstall