claude-cluster docs1.10.1
ReferenceRéférence

Local protocolProtocole local

The control socket (one JSON per line), the cluster-run wrapper messages, the web API endpoints and the MCP bridge.Le socket de contrôle (un JSON par ligne), les messages du wrapper cluster-run, les points d'accès de l'API web et le pont MCP.

1. Control socketSocket de contrôle

The core listens on a unix socket, $XDG_RUNTIME_DIR/claude-cluster/control.sock (CLAUDE_CLUSTER_SOCKET overrides it; the folder is 0700, the socket 0600: only your user reaches it). A connection carries any number of requests; each is one JSON object on one line and gets one JSON line back:

{"cmd": "list"}
{"ok": true, "data": [ ... ]}
{"ok": false, "error": "no such session: s9"}
FieldMeaning
cmdthe command: list, status, send, spawn, allow, mode, model, task_add, schedule_add, web, usage, taxonomy, settings_get, settings_set, heavy_run, job_*... (the headless commands of the CLI, plus the ones of the interfaces and the MCP tools)
sessionid (s1, g), name or name prefix
originset by the transport: mcp (the global session: its limits and its [mcp_tools] switches apply), sub (the small MCP of a sub-session, with owner: its own tasks and schedules only), web (a web device: read only for what the settings do not open)
client, v, buildan interface of another process: its id, the version of the state it has, its build id

Special commands: hello returns the version, build id, pid and binary of the core (an interface asks before attaching); sync is a long poll: it returns the whole state of the interface once its version v changes (up to 10 s), and is refused when the build id differs.

A request never stops the core: anything it throws is answered as {"ok": false, "error": "bad request: ..."}.

Le cœur écoute sur un socket unix, $XDG_RUNTIME_DIR/claude-cluster/control.sock (CLAUDE_CLUSTER_SOCKET le remplace ; le dossier est en 0700, le socket en 0600 : seul votre utilisateur l'atteint). Une connexion porte un nombre quelconque de requêtes ; chacune est un objet JSON sur une ligne et reçoit une ligne JSON en retour :

{"cmd": "list"}
{"ok": true, "data": [ ... ]}
{"ok": false, "error": "no such session: s9"}
ChampSens
cmdla commande : list, status, send, spawn, allow, mode, model, task_add, schedule_add, web, usage, taxonomy, settings_get, settings_set, heavy_run, job_*... (les commandes headless de la CLI, plus celles des interfaces et des outils MCP)
sessionidentifiant (s1, g), nom ou préfixe de nom
originposé par le transport : mcp (la session globale : ses limites et ses interrupteurs [mcp_tools] s'appliquent), sub (le petit MCP d'une sous-session, avec owner : ses propres tâches et planifications seulement), web (un appareil web : lecture seule pour ce que les réglages n'ouvrent pas)
client, v, buildune interface d'un autre processus : son identifiant, la version de l'état qu'elle a, son identifiant de build

Commandes spéciales : hello rend la version, l'identifiant de build, le pid et le binaire du cœur (une interface le demande avant de s'attacher) ; sync est une longue interrogation : elle rend tout l'état de l'interface dès que sa version v change (jusqu'à 10 s), et est refusée quand l'identifiant de build diffère.

Une requête n'arrête jamais le cœur : tout ce qu'elle lève est rendu en {"ok": false, "error": "bad request: ..."}.

2. cluster-runcluster-run

cluster-run [--class c] [--prio n] [--name x] [--cwd d] [--session id] -- cmd... talks to the same socket with a stream:

DirectionMessage
wrapper to core{"cmd":"job_run","session","class","prio","name","cwd","argv","wrapper_pid"}
core to wrapper{"ok":true,"event":"queued","id","position","total","waiting_for","eta_s"} (again when it changes)
core to wrapper{"ok":true,"event":"go","id","threads","profile","nice","io_class","io_level"}
wrapper to core{"event":"started","pid"}, later {"event":"exit","code","signal","tail"}
core to wrapper{"event":"killed","by","reason"}

The slot is released at exit or when the connection drops (the wrapper died: the command's process group is terminated). Without a core the wrapper runs the command directly; when the connection drops while queued it retries for 30 s, then runs directly.

cluster-run [--class c] [--prio n] [--name x] [--cwd d] [--session id] -- cmd... parle au même socket avec un flux :

SensMessage
wrapper vers cœur{"cmd":"job_run","session","class","prio","name","cwd","argv","wrapper_pid"}
cœur vers wrapper{"ok":true,"event":"queued","id","position","total","waiting_for","eta_s"} (de nouveau quand ça change)
cœur vers wrapper{"ok":true,"event":"go","id","threads","profile","nice","io_class","io_level"}
wrapper vers cœur{"event":"started","pid"}, puis {"event":"exit","code","signal","tail"}
cœur vers wrapper{"event":"killed","by","reason"}

Le créneau est libéré à exit ou quand la connexion tombe (le wrapper est mort : le groupe de processus de la commande est terminé). Sans cœur le wrapper lance la commande directement ; quand la connexion tombe pendant l'attente, il réessaie 30 s puis lance directement.

3. Web APIAPI web

The web access serves a single page and a small JSON API over https, only after login (the 6-digit code, then your approval); the session cookie is bound to the address of the device. The endpoints:

PathUse
/, /index.html, /sw.jsthe page and its service worker
/api/login, /api/logout, /api/ping, /api/versionauthentication, round trip, version (version is public)
/api/statethe state of the cluster (long poll)
/api/cmda control command (origin: "web")
/api/completecompletions of the prompt
/api/attach, /api/attach/file, /api/attach/link, /api/attach/list, /api/attach/removeattachments
/api/display, /api/filea display picture; a file of a display
/api/notify?since=Nthe notification log (long poll, the Android app)
/api/listen, /api/saythe voice of the page
/api/tty/* (open, read, write, resize, close, ws)the terminal mode, on its own port ([web] tty_port)
/ca.crt, /app.apkserved to anyone: the authority certificate and the Android app
/docs/*this documentation, served without login

L'accès web sert une page unique et une petite API JSON en https, seulement après connexion (le code à 6 chiffres, puis votre accord) ; le cookie de session est lié à l'adresse de l'appareil. Les points d'accès :

CheminUsage
/, /index.html, /sw.jsla page et son service worker
/api/login, /api/logout, /api/ping, /api/versionauthentification, aller-retour, version (la version est publique)
/api/statel'état du cluster (longue interrogation)
/api/cmdune commande de contrôle (origin: "web")
/api/completecomplétions du prompt
/api/attach, /api/attach/file, /api/attach/link, /api/attach/list, /api/attach/removepièces jointes
/api/display, /api/filel'image d'un affichage ; un fichier d'un affichage
/api/notify?since=Nle journal des notifications (longue interrogation, l'application Android)
/api/listen, /api/sayla voix de la page
/api/tty/* (open, read, write, resize, close, ws)le mode terminal, sur son propre port ([web] tty_port)
/ca.crt, /app.apkservis à tous : le certificat de l'autorité et l'application Android
/docs/*cette documentation, servie sans connexion

4. The MCP bridgeLe pont MCP

claude-cluster mcp speaks the Model Context Protocol on stdio. tools/list returns the tools; tools/call maps the tool name to a control command (session_display to display, jobs_add to job_add, ...) and sets origin. The environment variable CLAUDE_CLUSTER_SESSION makes it the MCP of a sub-session. A tool turned off in [mcp_tools] is refused at once with a message for the user.

claude-cluster mcp parle le Model Context Protocol sur stdio. tools/list rend les outils ; tools/call associe le nom de l'outil à une commande de contrôle (session_display vers display, jobs_add vers job_add, ...) et pose origin. La variable d'environnement CLAUDE_CLUSTER_SESSION en fait le MCP d'une sous-session. Un outil désactivé dans [mcp_tools] est refusé aussitôt avec un message pour l'utilisateur.