claude-cluster docs1.10.1
Advanced conceptsConcepts avancés

Orchestrator and cluster-runOrchestrateur et cluster-run

The queue for heavy jobs: why, how to use cluster-run and heavy_run, the limits that follow your hardware and the pressure rules.La file des travaux lourds : pourquoi, comment utiliser cluster-run et heavy_run, les limites qui suivent le matériel et les règles de pression.

With several sessions building and testing at once a computer saturates: load far above the cores, swap full, compilers crashing. The orchestrator is a small kernel scheduler for the heavy jobs (builds, tests, containers, media, GPU): they wait in a queue, a limited number run at once, and the limit follows the hardware, the live load and your settings. Light commands (ls, grep, git status) never go through it.

Quand plusieurs sessions compilent et testent en même temps, un ordinateur sature : charge très supérieure aux cœurs, swap plein, compilateurs qui plantent. L'orchestrateur est un petit ordonnanceur de noyau pour les travaux lourds (compilations, tests, conteneurs, média, GPU) : ils attendent dans une file, un nombre limité tourne en même temps, et la limite suit le matériel, la charge du moment et vos réglages. Les commandes légères (ls, grep, git status) n'y passent jamais.

1. Using itL'utiliser

WhereHow
a shell (a session's or yours)cluster-run [--class build|tests|container|gpu|custom] [--prio N] [--name x] -- <command>: waits (cluster-run: queued: position 2, waiting for slot (2/2 running) on stderr), then runs in the low profile (nice, ionice, -j / --parallel / MAKEFLAGS / CARGO_BUILD_JOBS lowered to the share granted); output and exit code pass through
MCP, a command that waitsheavy_run: returns the result (finished with exit code, duration, tail; failed; killed by whom) or the waiting status
MCP, no waitingjobs_add (woken with [job jN ...]), jobs_list, job_status, job_wait, job_kill, job_stop, job_resume, job_prio
the computerhardware_scan, orchestrator_config
interfacethe Tasks session (a Jobs section: queue, gauges, kill / stop / resume / priority), settings Orchestrator

cluster-run is installed next to claude-cluster and is in the PATH of every session. Without a running core it runs the command directly with a warning.

OùComment
un shell (celui d'une session ou le vôtre)cluster-run [--class build|tests|container|gpu|custom] [--prio N] [--name x] -- <commande> : attend (cluster-run: queued: position 2, waiting for slot (2/2 running) sur stderr), puis s'exécute en profil bas (nice, ionice, -j / --parallel / MAKEFLAGS / CARGO_BUILD_JOBS abaissés à la part accordée) ; sortie et code de retour sont transmis
MCP, une commande qui attendheavy_run : rend le résultat (fini avec code, durée, fin de sortie ; échoué ; tué par qui) ou l'état d'attente
MCP, sans attendrejobs_add (réveillé par [job jN ...]), jobs_list, job_status, job_wait, job_kill, job_stop, job_resume, job_prio
l'ordinateurhardware_scan, orchestrator_config
interfacela session Tasks (une section Jobs : file, jauges, tuer / arrêter / reprendre / priorité), réglages Orchestrator

cluster-run est installé à côté de claude-cluster et se trouve dans le PATH de chaque session. Sans cœur en marche, il lance la commande directement avec un avertissement.

2. Who sees whatQui voit quoi

The global session sees and manages every job. A sub-session adds, follows, waits for and kills its own jobs ([orchestrator] sub_add, sub_kill_own, sub_see_others). A closed or archived session loses its jobs.

La session globale voit et gère tous les travaux. Une sous-session ajoute, suit, attend et tue ses propres travaux ([orchestrator] sub_add, sub_kill_own, sub_see_others). Une session fermée ou archivée perd ses travaux.

3. Job statesÉtats d'un travail

queued -> running -> done | failed | killed
              \-> stopped (by you, or by pressure) -> running

A job starts only when the orchestrator is enabled, there is no pressure hold, active jobs are below the slots, its session and its class are below their limits and its RAM estimate fits. When nothing runs one job starts anyway so nothing starves. The order is 10 * prio plus session priority, a boost for the session you look at, and aging (a waiting job gains a point every aging_seconds), then FIFO.

queued -> running -> done | failed | killed
              \-> stopped (par vous, ou par la pression) -> running

Un travail ne démarre que si l'orchestrateur est actif, qu'il n'y a pas de blocage de pression, que les travaux actifs sont sous les slots, que sa session et sa classe sont sous leurs limites et que son estimation de RAM tient. Quand rien ne tourne un travail démarre quand même pour que rien ne reste affamé. L'ordre est 10 * prio plus la priorité de session, un bonus pour la session que vous regardez, et le vieillissement (un travail en attente gagne un point toutes les aging_seconds), puis FIFO.

4. LimitsLimites

  • Automatic: slots = min(usable cores x factor, (RAM - reserved) / RAM of a job), with factor 0.5 / 1 / 1.5 for the profile low / normal / max; RAM per class (build 2000 MB, tests 1200, container 1500, gpu 2000, custom 1000).
  • Manual: max_jobs, max_per_session, per class (gpu 1, container 2 by default), reserved_cpu, reserved_ram_mb, threads.
  • Pressure (load, MemAvailable, swap, /proc/pressure): at hold nothing new starts; at reduce running jobs are reniced and the lowest-priority newest one is stopped (SIGSTOP) until the load falls, then resumed with hysteresis. Never killed unless kill_on_oom = true.
  • Auto-detect: a process group outside the queue that burned detect_cpu_seconds of CPU is listed and its session is told once to use cluster-run.
  • Automatiques : slots = min(cœurs utilisables x facteur, (RAM - réservée) / RAM d'un travail), avec le facteur 0,5 / 1 / 1,5 pour le profil low / normal / max ; RAM par classe (build 2000 Mo, tests 1200, container 1500, gpu 2000, custom 1000).
  • Manuelles : max_jobs, max_per_session, par classe (gpu 1, container 2 par défaut), reserved_cpu, reserved_ram_mb, threads.
  • Pression (charge, MemAvailable, swap, /proc/pressure) : au niveau hold rien de nouveau ne démarre ; au niveau reduce les travaux en cours sont ralentis (renice) et le plus récent de plus basse priorité est arrêté (SIGSTOP) jusqu'à la baisse de charge, puis repris avec hystérésis. Jamais tués sauf kill_on_oom = true.
  • Détection automatique : un groupe de processus hors file qui a consommé detect_cpu_seconds de CPU est listé et sa session est prévenue une fois d'utiliser cluster-run.

5. Memory guardGarde mémoire

[orchestrator] memory_guard (on) watches, every 5 s and without any model, everything the sessions run - agents, their shells and background commands, sub-agents, heavy jobs, the global session too, never the core. Under guard_free_mb of memory available (0: 5 % of the RAM, at least 500 MB) it kills the biggest of them, its whole process tree, before the system's out-of-memory killer does: a command or job first (never one under guard_min_mb), an agent only when nothing else is big enough, the global session last. The session is told what was killed, how much it used and that it may run it again with less memory; a notice and a notification say it too. Settings > About / Processes shows the memory of each session, the free / total memory, the guard and its last kills.

[orchestrator] memory_guard (activé) surveille toutes les 5 s, sans aucun modèle, tout ce que les sessions font tourner - agents, leurs shells et commandes en arrière-plan, sous-agents, travaux lourds, la session globale aussi, jamais le cœur. Sous guard_free_mb de mémoire disponible (0 : 5 % de la RAM, au moins 500 Mo) il tue le plus gros d'entre eux, tout son arbre de processus, avant que le tueur de mémoire du système ne le fasse : d'abord une commande ou un travail (jamais sous guard_min_mb), un agent seulement quand rien d'autre n'est assez gros, la session globale en dernier. La session apprend ce qui a été tué, combien il utilisait et qu'elle peut le relancer avec moins de mémoire ; une notice et une notification le disent aussi. Réglages > About / Processes montre la mémoire de chaque session, la mémoire libre / totale, la garde et ses derniers arrêts.

6. HardwareMatériel

hardware_scan records the CPU, cores, RAM, swap, disk, GPUs and power in hardware.json, at start and on demand. The sample for pressure is read every second from /proc.

The full design (state machine, wrapper protocol, persistence) is in docs/orchestrator.md of the sources; the protocol page summarises the wrapper messages.

hardware_scan enregistre CPU, cœurs, RAM, swap, disque, GPU et alimentation dans hardware.json, au démarrage et à la demande. L'échantillon de pression est lu chaque seconde dans /proc.

La conception complète (machine à états, protocole du wrapper, persistance) est dans docs/orchestrator.md des sources ; la page protocole résume les messages du wrapper.