rigspark-cli 3.0.8

Which local LLMs can your computer run? Hardware-aware CLI with yes/slow/no verdicts and tok/s estimates, then verified installs via Ollama, llama.cpp, MLX or LM Studio.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
<h1 align="center">
  RigSpark
</h1>

<p align="center">
  <img src="assets/brand/3d/sparky-hero.webp" alt="Sparky, the RigSpark robot" width="420">
</p>

<h2 align="center">Know what your computer can run before you download it.</h2>

<p align="center">
  RigSpark is a hardware-aware native Rust CLI that gives local AI models a
  <strong>yes / slow / no</strong> verdict, explains the fit, and estimates
  tokens per second before you commit to the weights.
</p>

<p align="center">
  <a href="https://www.rigspark.si/">Website</a> ·
  <a href="#install-rigspark">Install</a> ·
  <a href="docs/references/guide.md">Guide</a> ·
  <a href="https://github.com/shashankswe2020-ux/rigspark/releases/latest">Latest release</a>
</p>

<p align="center">
  <a href="https://github.com/shashankswe2020-ux/rigspark/issues/new?template=bug_report.yml"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/btn-bug-dark.svg"><img src="assets/btn-bug-light.svg" alt="Report a bug" height="44"></picture></a>&nbsp;
  <a href="https://github.com/shashankswe2020-ux/rigspark/issues/new?template=feature_request.yml"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/btn-idea-dark.svg"><img src="assets/btn-idea-light.svg" alt="Suggest a feature" height="44"></picture></a>
</p>

<p align="center">
  <a href="https://github.com/shashankswe2020-ux/rigspark/actions/workflows/ci.yml"><img src="https://github.com/shashankswe2020-ux/rigspark/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://github.com/shashankswe2020-ux/rigspark/releases/latest"><img src="https://img.shields.io/github/v/release/shashankswe2020-ux/rigspark?sort=semver&label=release" alt="Release"></a>
  <a href="https://crates.io/crates/rigspark-cli"><img src="https://img.shields.io/crates/v/rigspark-cli.svg?label=crates.io" alt="crates.io"></a>
  <a href="https://docs.rs/rigspark-core"><img src="https://img.shields.io/docsrs/rigspark-core?label=docs.rs" alt="docs.rs"></a>
  <a href="rust-toolchain.toml"><img src="https://img.shields.io/badge/rust-1.98%2B-orange.svg?logo=rust" alt="Rust 1.98 or newer"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <a href="https://buymeacoffee.com/shashanksw9"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-support-FFDD00?logo=buymeacoffee&logoColor=black" alt="Buy me a coffee"></a>
</p>

> **New in 3.0:** a redesigned browser workspace. Every feature is still there,
> but each control appears only when you need it, and the Models view now loads
> the full ranked catalog.
> [See what changed →]CHANGELOG.md#300---2026-10-08

---

## Let Sparky check your rig

RigSpark keeps the first question simple: **will this model actually run here?**
The answer comes from a curated offline catalog and your detected hardware, not
from a download you have already waited for.

### 1. Install RigSpark

<p align="center">
  <img src="assets/brand/3d/sparky-wave.webp" alt="Sparky waving hello" width="250">
</p>

Homebrew on macOS or Linux:

```bash
brew install shashankswe2020-ux/tap/rigspark
```

On a Mac you can also install the desktop app: download `RigSpark_aarch64.dmg`
(Apple Silicon) or `RigSpark_x86_64.dmg` (Intel) from the
[latest release](https://github.com/shashankswe2020-ux/rigspark/releases/latest)
and drag RigSpark to Applications. The app is signed with a Developer ID and
notarized by Apple, so it opens without a Gatekeeper warning. The app bundles llama.cpp, so it needs no other
runtime: on first launch, **Download & start** fetches a verified starter model
that fits your Mac. It lives in the menu bar and launches at login (turn that
off in **Tools**); closing the window keeps your model serving, and
**Quit RigSpark** stops it. Updates install after their signature is verified.

On Windows, download `RigSpark_x64-setup.exe` from the
[latest release](https://github.com/shashankswe2020-ux/rigspark/releases/latest)
and run it. It installs for the current user without admin rights. The installer
is not code-signed yet, so if SmartScreen warns, choose **More info → Run
anyway**. The Windows app bundles a CPU build of llama.cpp, and its advice for
that runtime counts system memory only.

For the command line on Windows and other platforms, download a
[prebuilt archive](https://github.com/shashankswe2020-ux/rigspark/releases/latest),
extract it, and add the folder to `PATH`. Keep `rigspark`, `llmup`, and
`rigspark-gui` together.

The RigSpark binaries need no Node.js, Python, or compiler. Inference backends
have their own requirements.

> If Sparky helps you, please consider sponsoring the project:
> [https://buymeacoffee.com/shashanksw9]https://buymeacoffee.com/shashanksw9

[Cargo, checksums, unsigned macOS archives, and upgrades →](docs/references/guide.md#install)
· [Docker caveats →](docs/references/guide.md#docker)

### 2. Sparky sizes up your hardware

<p align="center">
  <img src="assets/brand/3d/sparky-chip.webp" alt="Sparky presenting a processor chip" width="300">
</p>

Start with advice. It is deterministic, works offline, and does not require an
inference backend:

```bash
rigspark recommend
rigspark can-run llama3.1:8b
rigspark catalog --all
```

- `recommend` ranks the catalog for this machine.
- `can-run` checks one model before you download it.
- `catalog --all` lets you browse the bundled model data.

Use `--json` for automation and `--accessible` for screen-reader-friendly
output. `llmup` remains a compatibility alias.

### 3. Read the face: yes, slow, or no

<p align="center">
  <img src="assets/brand/3d/sparky-lineup.webp" alt="Three Sparky robots showing the yes, slow, and no verdicts" width="760">
</p>

| Verdict | What Sparky means |
| --- | --- |
| **yes** | The model fits with the required headroom. |
| **slow** | It fits, but the expected experience may be constrained. |
| **no** | It does not safely fit the detected memory budget. |

Every verdict includes the reason. When RigSpark cannot source a figure, it says
`unknown` rather than inventing one. Throughput ranges are estimates, not
benchmarks.

### 4. Pick a model, verify it, and start

Once you have a fit, move from advice to a running model:

```bash
rigspark up llama3.1:8b    # pull, verify, and serve
rigspark chat              # chat with the active model
rigspark ls                # inspect managed models
rigspark switch            # change the active model
rigspark down              # stop when done
```

RigSpark supports:

- **Ollama** — recommended default and managed child process
- **llama.cpp** — native local serving
- **MLX** — Apple Silicon
- **LM Studio** — attach to an already running server
- **BitNet** — Microsoft's I2_S weights on CPU, using your compiled bitnet.cpp server

Managed weights pass an integrity check before serving. Servers bind to
`127.0.0.1` by default.

For Microsoft's official BitNet b1.58 2B-4T:

```bash
export RIGSPARK_BITNET_SERVER=/absolute/path/to/BitNet/build/bin/llama-server
rigspark up bitnet-b1.58:2b --backend bitnet --context 4096
rigspark chat
rigspark down
```

Build the server using [Microsoft's instructions](https://github.com/microsoft/BitNet).
On Apple Silicon, use the [tested pinned build and ARM patch](docs/references/guide.md#tested-apple-silicon-build);
unmodified builds can produce invalid output or crash, and BLAS must be disabled.
Stock llama.cpp cannot load this I2_S artifact. RigSpark downloads and verifies
the weights, not the runtime. Keep the variable set for chat, doctor and shutdown.
The initial integration is CPU-only; speed and KV-memory estimates stay unknown.
See the [per-model benchmark reports](benchmarking/README.md) for the recorded
BitNet chat results, methodology, and limitations.

[Backend setup and lifecycle details →](docs/references/guide.md#supported-backends)

#### Faster serving: speculative decoding and parallel agents

```bash
rigspark up qwen3:14b --backend llamacpp           # drafts with qwen3:0.6b automatically
rigspark up qwen3:8b --backend llamacpp --speculative ngram
rigspark up qwen3:14b --context 16384 --parallel 4 # four agents at once on Ollama
rigspark bench --concurrency 4                     # measure the active server
```

- `--speculative auto|draft|ngram|off`. On llama.cpp, models with a catalog
  drafter use it by default. RigSpark downloads the drafter, verifies its
  SHA-256 and reserves its memory before checking fit. If the drafter does not
  fit, RigSpark starts without it. `ngram` drafts from the context and needs no
  extra weights. Ollama handles speculative decoding inside its own model tags.
- `--parallel N` (1–16) sets concurrent request slots. llama.cpp slots share one
  unified KV pool. Ollama allocates a full context for each slot, so it needs
  `--context` and known KV geometry to size the memory (or `--bypass`).
- `rigspark bench` measures the active server with fixed, versioned prompts:
  time to first token, prefill and decode tok/s, draft acceptance, and
  combined throughput across concurrent requests. The prefill, decode and draft
  figures come from the runtime's own counters; anything it does not report
  shows as `unknown`.

#### Connect your coding agent

```bash
rigspark connect claude     # Claude Code via the local Anthropic Messages API
rigspark connect codex      # Codex via the local OpenAI Responses API
rigspark connect opencode   # OpenCode via an inline provider config
rigspark connect pi         # prints the snippet for Pi, Hermes, OpenClaw or Cline
```

`connect` points the agent at the active loopback server for that launch only.
It never rewrites the agent's own config files. Add `--dry-run` to print the
command and environment instead of starting the agent.

### 5. Continue in the browser workspace

```bash
rigspark gui
```

Choose a model, inspect the same hardware verdicts, chat, and use agents, skills,
and MCP tools from the loopback-only browser workspace.

- **One model chip** in the top bar holds the model, runtime, harness, and agent
  pickers.
- **Models** lists the whole ranked catalog with search, *Runs well / Slow /
  Won't fit* filters, and a **Fit settings** popover for context and KV cache.
- **The inspector** (⌘I, or click Sparky) shows live memory, CPU, disk, and the
  latest call's token usage. Sparky's mood follows real RAM pressure.
- **Light and dark themes**, with ⌘1–⌘5 to switch views.

<p align="center">
  <img src="assets/brand/screens/screenshot-gui.webp" alt="The RigSpark workspace Models view ranking local models with yes and slow verdicts, memory fit bars, and estimated tokens per second" width="820">
</p>

Local chat stays on your machine. Cloud harnesses and external tools can send
data to their own providers, so RigSpark keeps those boundaries visible.

[Browser workspace, agents, and tools →](docs/references/guide.md#browser-gui)

### 6. Let Sparky create images and short videos

<p align="center">
  <img src="assets/brand/3d/sparky-studio.webp" alt="Sparky in a studio spotlight" width="320">
</p>

RigSpark can orchestrate open-weight image and video models through your own
[ComfyUI](https://github.com/Comfy-Org/ComfyUI) installation.

```bash
rigspark catalog --generation
rigspark generate image --prompt "a lighthouse at dusk" --comfyui-dir ~/ComfyUI
rigspark generate video --prompt "a fox running in snow" --comfyui-dir ~/ComfyUI
rigspark generate --tui
```

Start ComfyUI on its default loopback address, `127.0.0.1:8188`. RigSpark
downloads pinned weights, verifies their SHA-256 digest, installs only its
built-in local workflows, and refuses paid Partner API nodes. Generation speed
stays `unknown` when no defensible measurement is available.

In `rigspark gui`, switch the composer from **Text** to **Image** or **Video**.
Generated media renders inline and is never sent to the language model.

For UI/UX mockups, select **ming-image:ming_image_0.1_design_int8_convrot**
under **Models → Image → Use in Chat**, then generate in Image mode. This exact
25.94 GB weight pairing was tested with ComfyUI 0.38.0 on a 36 GiB Apple Silicon
Mac. Other Ming variants remain fit-only; NVIDIA/CUDA and peak inference memory
are not certified. Generated lettering can be garbled.

```bash
rigspark generate ming-image:ming_image_0.1_design_int8_convrot \
  --prompt "A plant-care app onboarding screen, soft green palette, flat UI design" \
  --comfyui-dir ~/ComfyUI
```

<p align="center">
  <img src="assets/brand/screens/ming-design-gui.png" alt="A real Ming Design plant-care app mockup generated inline in RigSpark chat using local ComfyUI" width="720">
</p>

[Image and video generation specification →](docs/specs/image-video-generation.md)

---

## Why the answers are trustworthy

<p align="center">
  <img src="assets/brand/3d/sparky-peek.webp" alt="Sparky keeping watch" width="250">
</p>

- **Offline advice.** Recommendation commands use a bundled, curated catalog and
  make no network calls.
- **Honest unknowns.** Missing bandwidth, model geometry, or measurements stay
  visibly `unknown`.
- **Fail-closed integrity.** Managed weights must match their catalog digest, or
  a documented size-floor fallback, before RigSpark serves them.
- **Loopback by default.** Local servers listen on `127.0.0.1`, not the public
  network.
- **Reproducible decisions.** The same hardware and catalog produce the same
  recommendation.
- **One adapter boundary.** Ollama, llama.cpp, MLX, LM Studio, and BitNet sit behind the
  same runtime lifecycle and safety gates.

## Add any GGUF model from Hugging Face

The bundled catalog is curated and signed. For anything newer or more
specific, add it yourself:

```bash
rigspark add --search "qwen3 coder"          # search GGUF repositories
rigspark add unsloth/Qwen3-0.6B-GGUF          # list quants, add the largest that fits
rigspark add unsloth/Qwen3-0.6B-GGUF:Q4_K_M  # or name one
rigspark up hf.co/unsloth/qwen3-0.6b-gguf:q4_k_m --backend llamacpp
```

In the browser workspace, use **Models → Add from Hugging Face**.

RigSpark reads the repository and one GGUF header to size every
quantization against your machine. It then pins the repository commit and
each file's SHA-256 in `~/.rigspark/catalog/local.json`. `up` downloads
through llama.cpp or Ollama (`hf.co/owner/repo:quant`) and refuses to
serve weights whose digest does not match. Repositories need a recognized
open-weight license. Projector files and split (multi-part) GGUFs are
skipped.

Added models appear in `recommend`, `can-run` and the GUI marked *added by
you*. Remove one with `rigspark add --remove <id>`. Network access happens
only when you search or add; advice stays offline.

## Update the catalog when you choose

Catalog updates are explicit; recommendations and normal startup remain
offline.

```bash
rigspark catalog --status
rigspark catalog --update
```

RigSpark verifies the signed catalog before activating it atomically. An invalid
signature, incompatible schema, or network failure leaves the current snapshot
unchanged. Recovery falls back through the previous verified snapshot and then
the bundled catalog, with visible warnings.

New models arrive weekly. A scheduled pipeline admits every new Ollama library
model whose facts it can read from the shipped artifact (size, digest, context,
architecture, open license), plus Comfy-Org image and video releases, and
publishes a signed catalog once the quality gate passes. These entries are marked
**auto-sourced**, keep fail-closed digest verification, and show `unknown` for
anything that could not be sourced. Image and video models without a built-in
workflow yet get a fit verdict and are labelled *workflow coming*.

```bash
rigspark recommend --month 1        # only models released or added in the last month
rigspark catalog --all --month 3
```

In the terminal UI, `m` cycles the same 1, 2 and 3 month windows; the browser
workspace has a **Released in** selector.

`rigspark catalog --refresh` is a maintainer preview of enrichment against the
bundled registry snapshot; it does not install a published catalog.

[Catalog provenance, trust, and recovery →](docs/references/guide.md#independent-catalog-updates)

## A 20-second tour

[![RigSpark demo showing terminal recommendations and the browser workspace](assets/rigspark-preview.gif)](assets/rigspark.mp4)

The tour runs `rigspark recommend`, shows models that do and do not fit, then
opens the same verdicts and a local chat in `rigspark gui`.

[Watch in 1080p with sound](assets/rigspark.mp4) ·
[Earlier demo on YouTube](https://youtu.be/MI2wfI1eeCM?si=QA2teeDmeT_fNIqf)

## Find your next command

| Goal | Command |
| --- | --- |
| Rank models for this machine | `rigspark recommend` |
| Check one model | `rigspark can-run <model>` |
| Diagnose hardware and runtimes | `rigspark doctor` |
| Browse text models | `rigspark catalog --all` |
| Browse image and video models | `rigspark catalog --generation` |
| Start a verified model | `rigspark up <model>` |
| Open the terminal UI | `rigspark` |
| Open the browser workspace | `rigspark gui` |
| Generate local media | `rigspark generate` |
| Benchmark the active server | `rigspark bench` |
| Connect a coding agent | `rigspark connect <agent>` |
| Add a model from Hugging Face | `rigspark add <owner/repo>` |
| Stop the active model | `rigspark down` |

Run `rigspark --help` for the complete CLI.

## Project map

- [`crates/rigspark-core/`]crates/rigspark-core/ — catalog, memory sizing,
  ranking, advice, and reports
- [`crates/rigspark-runtime/`]crates/rigspark-runtime/ — hardware detection,
  backend adapters, lifecycle, state, and harnesses
- [`crates/rigspark-gui/`]crates/rigspark-gui/ — loopback HTTP/SSE host and
  embedded browser client
- [`crates/rigspark-cli/`]crates/rigspark-cli/ — native CLI, terminal UI, and
  catalog maintenance
- [`apps/desktop/src-tauri/`]apps/desktop/src-tauri/ — native desktop shell

## Build from source

RigSpark is a Rust workspace pinned to Rust 1.98.1:

```bash
cargo build --workspace --locked
cargo test --workspace --locked -- --test-threads=2
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo fmt --all -- --check
cargo native-retirement
```

No Node.js or TypeScript tooling is part of the project.

## Keep exploring

- [Commands, custom context, and installed models]docs/references/guide.md#commands
- [Terminal UI]docs/references/guide.md#terminal-ui
- [How hardware advice works]docs/references/guide.md#how-advice-works
- [Scripting and exit codes]docs/references/guide.md#scripting--exit-codes
- [FAQ]docs/references/guide.md#faq and [troubleshooting]docs/references/guide.md#troubleshooting
- [Development guide]docs/references/guide.md#development
- [Project specification]docs/specs/rigspark.md
- [Changelog]CHANGELOG.md

<p align="center">
  <img src="assets/brand/3d/sparky-cheer.webp" alt="Sparky celebrating" width="320">
</p>

<p align="center">
  <strong>Let Sparky check your rig.</strong><br>
  <a href="https://github.com/shashankswe2020-ux/rigspark/releases/latest">Download RigSpark</a> ·
  <a href="https://github.com/shashankswe2020-ux/rigspark">Star on GitHub</a> ·
  <a href="https://buymeacoffee.com/shashanksw9">Buy me a coffee</a>
</p>

## Support RigSpark

RigSpark is free, MIT-licensed, and built in spare time. If it saved you a
download that would never have run, you can
[buy me a coffee ☕](https://buymeacoffee.com/shashanksw9).

---

[MIT License](LICENSE)

**Keywords:** local LLM, run LLM locally, LLM hardware requirements, VRAM
calculator, tokens per second, Ollama, llama.cpp, MLX, LM Studio, Rust CLI.