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, SWARM_API_TOKEN or ~/.swarm/config.toml, else the sign-in from swarm login (browser; --device for a machine without one)
  • 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 none|fixed_int2..8|learned_bottleneck] [--pretrained REPO] [--freeze-backbone] [--lora [--lora-r N] [--lora-alpha N] [--lora-targets a,b] [--lora-export merged|adapters]] [--plan | --dry-run] [--wait]
  • swarm sweep (--config PATH | --name CONFIG_ID) [--partition equal|weighted] [--dry-run] [--continue-on-fail]
  • swarm jobs [--status STATUS] [--format json]
  • swarm jobs show JOB_ID [--format json]
  • swarm stop JOB_ID [--timeout SECONDS]
  • swarm resume JOB_ID (a stopped pipeline run, from its last committed snapshot)
  • 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] [--top-p FLOAT] [--top-k N] [--min-p FLOAT]
  • swarm model-unload MODEL_ID [--fellow-id N]

MCP (use SilentSwarm from an AI agent)

  • swarm mcp config [--client claude-code|claude-desktop|cursor|vscode|json] [--toolsets a,b|all] [--auth token|oauth] prints ready-to-paste client setup for this leader; the token stays a $SWARM_API_TOKEN placeholder and is never printed; --auth oauth is the keyless setup (the client signs in through the browser). The web UI's AI agents page (/agents) shows the same, and lists connected apps
  • swarm mcp serve [--toolsets a,b|all] [--token TOKEN] [--debug] stdio MCP server for clients that start a command (Claude Desktop); forwards every message both ways to the leader's Streamable HTTP endpoint, with the API token or, without one, swarm login's sign-in (renewed as it expires)
  • swarm login [--device] [--scopes read,operate,admin] [--no-browser] sign the CLI in through the browser instead of an API token; swarm logout ends it (also listed and ended under AI agents - Connected apps)
  • swarm mcp tools [--toolsets a,b|all] [--format json] the tools your token can call (read / write / destructive)
  • toolsets: cluster, training, buckets, serving, pools, orgs, account, admin, meta; default cluster,training,buckets,serving,meta
  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; a pipeline run that stopped (or lost its nodes for a while) continues with resume.
  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
  • train --plan -> POST /api/v1/jobs/plan (nothing is submitted)
  • jobs list -> GET /api/v1/jobs
  • jobs show -> GET /api/v1/jobs/{job_id} (config.placement_plan, split_plan, stage_assignments)
  • stop -> DELETE /api/v1/jobs/{job_id}
  • resume -> POST /api/v1/jobs/{job_id}/resume
  • 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
  • mcp serve / mcp tools -> POST|GET|DELETE /mcp[/] (Streamable HTTP)

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.