Guides

CLI reference

One binary, forge, drives the whole cluster. It talks to the local agent, which gossips your intent to the rest of the pool. Every command works from any node.

Global flags — --network <name> targets a specific cluster, --json makes output machine-readable, -h prints help for any command.

All commands

clystria init clystria join clystria leave clystria status clystria nodes clystria top clystria logs clystria deploy clystria scale clystria models clystria undeploy clystria drain clystria heal clystria config clystria upgrade

Cluster

clystria init

$ clystria init <name> [--bind <addr>]

Create a new named cluster on the current machine and print a join token for other nodes.

--bind <addr>Network interface to advertise on. Default: auto-detected LAN IP.

--token-ttl <dur>How long the join token stays valid. Default: 24h.

$ clystria init home
# ✔ home created · join token: fg_7Kp2…9xQ

clystria join

$ clystria join --network <name> --token <token>

Fuse this machine into an existing cluster. The agent profiles local GPUs and adds them to the pool.

--network <name>Name of the cluster to join.

--token <token>Join token from `clystria init`.

--label <k=v>Attach labels (e.g. zone=rack-a) for placement hints.

$ clystria join --network home --token fg_7Kp2…9xQ
# ✔ fused · pool now 14 nodes · 512 GB VRAM

clystria leave

$ clystria leave [--force]

Gracefully remove this node from its cluster, draining any layers it hosts onto other nodes first.

--forceLeave immediately without draining. The control loop will self-heal.

$ clystria leave
# → draining 6 layers… ✔ node removed

Observe

clystria status

$ clystria status [--json]

Print a one-glance overview of the cluster: node count, pooled VRAM, running deployments, and health.

--jsonEmit machine-readable JSON instead of the table.

$ clystria status
▸ home · 14 nodes · 512 GB VRAM · 3 models · healthy

clystria nodes

$ clystria nodes [<node>] [--watch]

List every node with its GPU, VRAM, occupancy and health — or inspect one node in detail.

<node>Show detailed topology and layers for a single node.

--watchLive-refresh the table.

$ clystria nodes
NODE        GPU          VRAM   USED   TOK/S  STATUS
srv-01      H100 SXM     80 GB  56 GB  640    live
mac-01      M3 Ultra     192GB  77 GB  310    live

clystria top

$ clystria top

A live TUI of the cluster — per-GPU utilization, KV-cache pressure, token economics and thermal map. Like htop for your cluster.

$ clystria top
# ┌ GPUs ─────────────┐ ┌ Throughput ──────┐
# │ ▇▇▇▆▅ 14 active    │ │ 1,940 tok/s      │

clystria logs

$ clystria logs [<deployment>] [--follow]

Stream structured logs from the control loop or a specific deployment.

<deployment>Scope logs to one deployment.

--follow, -fTail live.

--since <dur>Only logs newer than, e.g. 15m.

$ clystria logs chat-prod -f
12:04:11 route  req#8821 → srv-01 (queue: 2)
12:04:11 kv     cache hit 0.71 · evict 12 pages

Models

clystria deploy

$ clystria deploy <model> [flags]

Deploy a model across the pool. Clystria resolves the source, picks quantization, plans placement, and exposes an OpenAI-compatible endpoint.

--quant <fmt>fp16 · fp8 · awq · gptq · fp4. Default: auto-fit to available VRAM.

--replicas <n|auto>Number of replicas, or `auto` for latency-driven autoscaling.

--max-context <n>Maximum context window to provision KV-cache for.

--name <name>Name this deployment. Default: the model name.

--strategy <s>rolling | recreate for updates. Default: rolling.

$ clystria deploy llama-3.1-70b --quant awq --replicas auto
✔ live at http://home.local:8080/v1 · 1,940 tok/s

clystria scale

$ clystria scale <deployment> --replicas <n|auto>

Change replica count for a running deployment. Scale-out is warm; scale-in drains gracefully.

--replicas <n|auto>Target replicas or `auto`.

--target-latency <ms>For autoscaling: the p95 latency to hold.

$ clystria scale chat-prod --replicas auto --target-latency 250ms

clystria models

$ clystria models [--registry]

List running deployments, or browse the curated registry of ready-to-forge models.

--registryShow the Clystria model registry instead of running deployments.

$ clystria models
NAME        MODEL          REPLICAS  GPUS  TOK/S  STATUS
chat-prod   mistral-large  2         4     2,310  live

clystria undeploy

$ clystria undeploy <deployment>

Tear down a deployment and return its VRAM to the pool. In-flight requests drain first.

$ clystria undeploy chat-prod
# → draining… ✔ freed 4 GPUs · 156 GB back to pool

Operate

clystria drain

$ clystria drain <node>

Evacuate all layers off a node ahead of maintenance. The scheduler re-forges them onto survivors before the node goes quiet.

$ clystria drain srv-02
# → migrating 5 layers to srv-01, ws-01… ✔ safe to power off

clystria heal

$ clystria heal [--rebalance]

Force the control loop to re-evaluate placement now instead of waiting for the next low-traffic window.

--rebalanceAlso migrate layers toward the current optimal placement.

$ clystria heal --rebalance
# → found better placement (+8% tok/s) · migrating…

clystria config

$ clystria config get|set <key> [value]

Read or update cluster-wide settings — routing policy, autoscaling bounds, telemetry.

$ clystria config set routing.policy least-latency
$ clystria config get autoscale.max-replicas

clystria upgrade

$ clystria upgrade [--node <node>]

Roll the agent binary across the cluster with no downtime — one node at a time, draining each first.

--node <node>Upgrade a single node instead of the whole fleet.

$ clystria upgrade
# → rolling agent v0.1.0 → v0.1.1 across 14 nodes…