Skip to content

SilentSwarm CLI guide for LLMs

This document is optimized for prompting and tool-use planning by LLM agents.

Environment context

  • default_leader_url: https://silentswarm.nexpatch.ai
  • auth: optional bearer token via --token or ~/.swarm/config.toml
  • output_formats: table, json

Core command surface

  • swarm nodes [--filter status=ready] [--format json]
  • swarm devices [--filter status=ready] [--node HOST] [--format json]
  • swarm fellows [--format json]
  • swarm release --fellow-id N [--fellow-id M] | --all
  • swarm set-speed --fellow-id N [--tx-mbps X] [--rx-mbps Y]
  • swarm configs [--configs-dir DIR] [--format json]
  • swarm train --config PATH [--partition equal|weighted] [--compression ...] [--wait]
  • swarm sweep (--config PATH | --name CONFIG_ID) [--partition equal|weighted] [--dry-run] [--continue-on-fail]
  • swarm jobs [--status STATUS] [--format json]
  • swarm stop JOB_ID [--timeout SECONDS]
  • swarm watch JOB_ID [--refresh-rate FLOAT]

Inference command surface

  • swarm models
  • swarm model-load MODEL_ID [--fellow-id N] [--device cuda:0] [--wait] [--timeout SECONDS]
  • swarm infer MODEL_ID PROMPT [--max-tokens N] [--temperature FLOAT]
  • swarm model-unload MODEL_ID [--fellow-id N]
  1. Read current topology and health via nodes/devices/fellows.
  2. Normalize fellow set (release stale fellows, set speed limits).
  3. Launch one train run or a queued sweep.
  4. Poll with jobs or stream with watch.
  5. On issues, stop job and retry with adjusted parameters.
  6. Serve a finished model: models -> model-load --wait -> infer.

API mapping used by CLI

  • nodes -> GET /api/v1/cluster/nodes
  • devices -> GET /api/v1/cluster/devices
  • fellows -> GET /api/v1/workers
  • release single -> DELETE /api/v1/workers/{fellow_id}
  • release batch/all -> POST /api/v1/workers/release
  • set-speed -> POST /api/v1/workers/{fellow_id}/network-limit
  • train/sweep submit -> POST /api/v1/jobs
  • jobs list -> GET /api/v1/jobs
  • stop -> DELETE /api/v1/jobs/{job_id}
  • watch -> GET /api/v1/jobs/{job_id}/metrics/stream
  • models -> GET /api/v1/models
  • model-load -> POST /api/v1/models/{model_id}/load (+ .../status when --wait)
  • model-unload -> POST /api/v1/models/{model_id}/unload
  • infer -> POST /api/v1/chat/completions

Pool health (read-only, useful before placing work)

  • GET /api/v1/pools -> pools you can see
  • GET /api/v1/pools/{pool_id}/metrics -> one snapshot: serving throughput, per-node grades, deployed models, capacity_ready
  • GET /api/v1/pools/{pool_id}/events -> node joins/drops/grade changes

Notes

  • Sweep is sequential: submit run, wait for terminal state, submit next.
  • set-speed stores limits in leader registry for control-plane workflows.
  • A signal a node never reported is null, not 0 - do not read a missing metric as a zero measurement.
  • model-load can be refused with 409 when the stage's weights plus its KV cache do not fit the target node; the message carries the numbers.