Skip to main content

Orchestrators

Above your environments, the sidebar's ERUN section lists your host-side orchestrators — AI sessions that coordinate work across the environments you link to them. For a remote-agent or local-agent environment that means reviewing its code on your machine and delegating every change to the Agent inside it; for a host environment it means working in that environment's directory directly, since a host environment is a plain directory with no pod and therefore no Agent in there to delegate to and nothing that syncs over your edits; for a runtime environment, linked with the Runtime role below, it means operating that environment directly instead. Open an orchestrator's … menu to manage it: restart, delete, or reveal the guidance it operates under.

Orchestrator details on hover. Hover a running orchestrator's row to see what it's doing and, for each linked environment, its own state rather than just its name: busy (naming the holder when it's known), idle, in outage, or not open from this desktop, plus its usage figure and age when one has been read — the same activity and usage this environment's own hover card reports, so the two can never disagree. A Nudges line reports whether ERun has had to restate its pacing contract to a quiet session, how many times, and whether it has stopped nudging after repeated attempts — a capped session needs your reply or a restart, since ERun has stopped acting on its behalf. A session ERun did not start — one you launched in a terminal, or one an earlier ERun window left running — is shown here too, and its Nudges line says Not paced from this desktop: ERun can only restate the contract into a pane it owns, so that session is running without that safety net. The line names this desktop rather than the session on purpose, since the session itself may be perfectly healthy and paced from somewhere else.

Whip: push everything by hand. The titlebar carries a whip button (beside the theme toggle) that runs the same pacing pass immediately, across every live orchestrator and every environment's own AI session — not only the ones that have gone quiet long enough for the automatic pass to notice on its own. Clicking it opens a report naming every target: Pushed, Capped (already at the automatic pass's consecutive-nudge limit — reply in its pane or restart it), Failed (a push was attempted and refused — the report names the error), or Skipped, with the reason (not alive — no live session to push, for example). Whip never restarts or interrupts anything, so it needs no confirmation and is safe to click at any time. See erun whip for the same pass from the CLI, and pacing for the message text and cap semantics both share.

Editing a running orchestrator's environments takes a restart to apply. Its session already holds the AI tooling for the environments it started with, and that can't be swapped out from under it — so saving a different set in Manage doesn't touch a session that's already running. The row's status dot and the hover card both say so ("Restart to apply") until you do, and the manage dialog carries the same Restart action right there, next to the reason. Editing a stopped orchestrator needs no restart: its next start already picks up the new set.

Role, per linked environment. Beside each checked environment's directory field, a Role control says what this orchestrator uses that environment for: Code (writes code, iterates fast, not sized for a full regression run), Build (checks out pushed branches, runs the gates, cuts releases), Runtime (operates the environment directly — deploy, pin, observe), or Not declared — the default, and never silently coerced to any of the other three. The control shows only for a checked environment, and a line beside it states what the selected value means. Role is independent of the environment's own type: a remote-agent or local-agent environment accepts any of the four values, a host environment any but Runtime — that role means deploy, pin, and observe, and a host environment has no pod for any of them to act on, so the dialog does not offer it there — while a runtime environment accepts only the Runtime role, the dialog offering just that one choice since it has no worktree to review and no in-pod agent to delegate to, and so carries no directory field at all. Changing a role while the orchestrator is running carries the same restart-to-apply notice as changing the linked environment set, so the dialog never implies an edit took effect before you've confirmed it did. erun orchestrator set-role (see CLI · erun orchestrator) sets the same field from the terminal, so config.yaml is never the only writer.

Each orchestrator runs under two layers of guidance, and the dialog opens either one in your editor (VS Code or IntelliJ):

  • Role — what this orchestrator does. Yours to edit; ERun creates it once and never overwrites it.
  • Shared contract — the rules every orchestrator follows. ERun-managed and rewritten on every launch, so edits here don't stick.

For the exact files behind these two layers and how they're injected into a session, see Agent reference · Skills spec.

Your own directories. An orchestrator can also be pointed at directories that belong to no environment at all — a scratch checkout, a folder of notes, a second copy of a repo you build natively. They carry no tenant, no runtime version or image, and no role, because none of those describe a path with no pod behind it: nothing is registered for one, no deploy applies, and nothing else owns it, so the orchestrator authors and builds in it directly, exactly as it does in a host environment's own directory. Add directory… opens a folder picker, and each row carries its own remove control. A directory is a complete definition on its own: an orchestrator that names only directories and links no environment at all is valid, which is what makes this the way to point an orchestrator at a path without registering an environment for it first. Unlike the linked environments, changing them raises no restart notice — nothing a session resolved at launch is keyed on a directory, so the change is picked up the next time the orchestrator reads its own definition.

The conversation an orchestrator comes back to​

An orchestrator keeps one long conversation, and starting it — after a quit, a reboot, a crash, or a rebuild-and-restart — resumes that conversation rather than beginning a new one. By default that is the conversation derived from the orchestrator's own name: the same one on every launch and on every machine, so nothing on disk can point it somewhere else. A session that ends up in a conversation of its own — after a /clear, after a compaction, or because the harness declined the id it was asked to resume — does not move that default on its own. Its conversation is kept and offered, and Attach in the manage dialog is how you make it the one that comes back.

When a session's own conversation is still on this machine and differs from the one the launch resumes, ERun says so instead of coming back looking healthy with hours of the work missing. The message names both conversations — the one it resumed and the one the session was actually working in — and the manage dialog is where you settle it.

The dialog's Conversation section lists every conversation this orchestrator could resume, newest first, each with when it was last written, how large it is, the folder it was started in, and how it opens, so you can recognise the one holding your work. Each row says what it is to this orchestrator:

  • Live — its own session reported being in this one.
  • Stranded — recorded as live by a session ERun can no longer confirm. This is the row to look at when work has gone missing.
  • Attached — the one you chose.
  • Default — the conversation this orchestrator's name resolves to, used until anything else is known.
  • Unclaimed — a conversation on this machine that no orchestrator is using.

Attach restarts the orchestrator in the conversation you picked and remembers the choice, so later starts honour it rather than going back to the default; Use the default clears it again. Conversations belonging to your other orchestrators are never offered here — the list says how many it left out — because handing one orchestrator another's history is worse than starting fresh.

Where next​

  • Diagnostics console — an orchestrator's own log, for a fault that belongs to the app itself.
  • erun whip — why the CLI can only report orchestrators as unreachable, and the desktop is the only place that can push them.