Grant
ae8efa1754
- image/ FastAPI app: /api/status, /api/swap, /api/swap/{id}/stream, /api/test-connection
- models.yaml: 5-model catalog (qwen3-vl, gemma4, qwen36, qwen3-235b-fp8, qwen25-72b)
- README, runbook, known-issues
- Dry-run swap verified against live Spark 1 (gemma4 currently loaded)
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
# spark-control
|
|
|
|
A browser-based control panel for a dual-DGX-Spark vLLM cluster. Designed to run as a [StartOS 0.4](https://docs.start9.com/packaging/0.4.0.x/) package on a Start9 server on the same LAN as the Sparks.
|
|
|
|
## What it does
|
|
|
|
- Shows which LLM is currently loaded on the cluster (`:8888/v1/models`).
|
|
- Click to swap to a different model — stops the current one, launches the new one, streams logs to the UI until `Application startup complete.` appears.
|
|
- Surfaces health for Parakeet (STT, `:8000`) and Magpie (TTS, `:9000`) on Spark 2.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
[Browser/phone] ──► [StartOS reverse proxy] ──► [spark-control container]
|
|
│ (SSH over LAN)
|
|
▼
|
|
[Spark 1] ──► launch-cluster.sh
|
|
│
|
|
▼
|
|
[Spark 2]
|
|
```
|
|
|
|
Two layers in this repo:
|
|
|
|
- `image/` — a self-contained FastAPI app + static UI. Runs anywhere with `uvicorn` and an SSH client. Useful for development.
|
|
- `package/` — a thin StartOS 0.4 wrapper that packages the image, exposes the UI on the LAN, and gives the user actions to configure SSH access to the Sparks.
|
|
|
|
## Quick start (local dev, no StartOS yet)
|
|
|
|
```bash
|
|
cd image
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -e .
|
|
export SPARK1_HOST=<spark-1-host>.local
|
|
export SPARK1_USER=<spark-user>
|
|
export SPARK2_HOST=<spark-2-ip>
|
|
export SPARK2_USER=<spark-user>
|
|
export SSH_KEY_PATH="$HOME/Library/Application Support/NVIDIA/Sync/config/nvsync.key"
|
|
uvicorn app.server:app --host 0.0.0.0 --port 9999 --reload
|
|
```
|
|
|
|
Open <http://localhost:9999>.
|
|
|
|
## Repo layout
|
|
|
|
- `models.yaml` — model catalog (also bundled into the image)
|
|
- `image/` — Docker image source
|
|
- `package/` — StartOS 0.4 package source
|
|
- `scripts/build-s9pk.sh` — convenience wrapper around the StartOS build
|
|
- `runbook.md` — operating notes
|
|
- `known-issues.md` — known quirks and workarounds
|
|
|
|
## Status
|
|
|
|
v0.1 — local-only, single-cluster, no auth (trusts LAN).
|