Connect your first agent

One click, about three seconds, then one prompt to check it worked. If you want to know what Runi added to your machine before you press it, that is further down.

Connect it#

1. Open Settings → Agents#

   Every agent Runi speaks to is listed, with the ones it can detect on this machine marked. You can connect an agent Runi has not detected; it will have nothing to observe until you install that agent.

2. Press Connect, and read the two lists#

   The dialog states what Runi will do and what it will never do for that specific agent, because the answer differs between them. Both lists are generated from the same registry the adapters are built against, so they cannot drift from the code.

3. Confirm your account password if asked#

   Runi signs the daemon in separately from the app, so publishing from this machine can never sign you out of the window you are looking at. That second sign-in is what needs the password. It is asked once per machine, not once per agent.

4. Start a session and check it arrived#

   Open your agent in a repository your workspace tracks and give it one prompt. Within a few seconds the session appears under Sessions in the app.

What Runi added to your machine#

Everything below is user-level config for that agent. Runi never writes into your repository, and never touches a project-scoped config file. Disconnecting removes all of it again.

Alongside those, the connect writes ~/.relay/config.json: which workspace this machine publishes to, which repositories it tracks, your ignore patterns, and your two sharing switches. That file is the daemon's whole idea of who you are.

Hooks stay installed. That is not the same as always on#

Hooks are registered at the user level, so they exist for every session you start on this machine. Outside the repositories your workspace tracks they do nothing: Runi publishes nothing, injects nothing, and your agent runs exactly as it did before.

This is the trade that makes the product bearable to install. You never have to remember to turn Runi on for the right project. You tell it once which projects count. See Repositories.

Check it worked#

Registration and firing are different things. A hook can be written perfectly into a settings file the agent never reads. The doctor compares what is registered against what has arrived:

$ runi doctor

A healthy machine looks like this:

Runi doctor
  ok   config    workspace 8f2c… as Ravjeet (~/.relay/config.json)
  ok   auth      cached access token valid for another 52 min
  ok   hooks     all 6 Claude Code events registered and their scripts exist
  ok   publish   last event published 3 min ago
  ok   outbox    empty — nothing waiting to replay
  ok   this repo relay is tracked — sessions here publish to the workspace

If the doctor is not on your path, it sits beside the daemon at ~/.relay/relay-doctor. Every line it can print is explained in Reading runi doctor.

Disconnecting#

Settings → Agents, then deselect the agent. Runi withdraws its entries: the hook lines and the MCP registration come back out of that agent's config. This matters. An orphaned registration pointing at a daemon that is gone makes the agent report a broken server on every launch, which looks like the agent's fault.

If the connect fails#

Anything else is almost always covered by Nothing is appearing in Runi, which walks the seven causes in the order worth checking.