./deploy-courseware.sh installs and configures the environment, then starts every managed service.
./destroy-courseware.sh stops the managed services, uninstalls courseware-managed Ollama, and removes the project-owned lab state.
./labctl provides day-two controls such as assets lab2, start, stop, status, urls, logs, and open kiln.

What It Installs

Ollama
llama.cpp
Netron, served locally on port 8338
Open WebUI
ChunkViz
Embedding Atlas
Promptfoo
Unsloth Studio
Kiln Desktop
Course-specific support assets for lab 1, lab 2, and lab 4

Lab 1 Defaults

Lab 1 is now provisioned directly by the installer:

The Qwen3-0.6B-Q8_0.gguf and Llama-3.2-1B.Q4_K_M.gguf files are mirrored into state/models/lab1/.
The Qwen GGUF is pre-registered in Ollama as lab1-qwen3-0.6b-q8_0.
The wiki serves same-host download links for both GGUFs through /api/lab1/models/....
Lab 1 confidence visualization requires Ollama 0.12.11 or newer because it depends on logprobs.

Supported Host Profiles

This build intentionally avoids the reference VM's hardware workarounds.

macOS: Apple Silicon only, with at least 16 GB unified memory.
Native Debian/Ubuntu: Debian-family Linux with an NVIDIA GPU visible to nvidia-smi and at least 8 GB VRAM.
WSL: Debian/Ubuntu-family Linux running under WSL, with the NVIDIA GPU exposed into the distro.

The launcher and Ansible preflight classify the host dynamically and apply different setup behavior for:

macos
native-debian-ubuntu
wsl

WSL Check

If you run this inside WSL, the launcher checks GPU readiness before Ansible starts.

If that check fails, fix WSL first:

Install or update the NVIDIA Windows driver with WSL/CUDA support
Run wsl --update in Windows PowerShell
Run wsl --shutdown
Reopen WSL and confirm nvidia-smi works

Important: nvidia-smi is only the driver check. Building CUDA-enabled llama.cpp also requires the Linux-side CUDA toolkit inside the distro.

On Linux and WSL, the first ./labctl up or ./labctl preflight run may prompt once for your sudo password so Ansible can install system packages.

On Ubuntu WSL x86_64, preflight now installs the Linux-side CUDA toolkit automatically if it is missing.

It first tries the distro package:

sudo apt install -y nvidia-cuda-toolkit

If that package is unavailable or still does not expose nvcc, the installer falls back to NVIDIA's WSL-Ubuntu repository bootstrap for the toolkit only, not a Linux GPU driver.

If the automatic bootstrap still fails, verify:

nvcc --version
ls /usr/local/cuda/include/cuda_runtime.h

For non-Ubuntu WSL distros, install the CUDA toolkit manually before running the deploy script.

Native Debian/Ubuntu CUDA Behavior

On native Debian/Ubuntu hosts, the installer handles three CUDA-toolkit cases:

If the toolkit is already usable, it reuses the existing install instead of forcing a reinstall.
If the distro exposes nvidia-cuda-toolkit, it installs that package.
If the distro package is unavailable, it bootstraps NVIDIA's official CUDA network repository for supported native Debian/Ubuntu releases and installs the toolkit from there.

If apt starts in a broken dependency state, the installer attempts dpkg --configure -a and apt-get --fix-broken install before retrying package installation.

If CUDA is already mounted or preinstalled outside PATH, the installer detects standard locations such as /usr/local/cuda/bin/nvcc and /usr/local/cuda-*/bin/nvcc.

Standard Assumptions

The default deployment is centered on Ollama-backed local inference and browser-based tools such as Netron and the wiki.
Netron is installed into a managed Python virtual environment and served locally instead of being provisioned as a desktop package.
Lab 1 model downloads are mirrored locally during ./labctl up, so students do not have to fetch them manually from the original source.
WhiteRabbitNeo assets remain a separate Lab 2 flow and are still handled outside the default ./labctl up run.
Run ./labctl assets lab2 when you want to populate repo-local Lab 2 assets in assets/lab2/ from Hugging Face.
After base setup, run state/lab2/download_whiterabbitneo-gguf.sh to fetch only the Q4_K_M, Q8_0, and IQ2_M files from bartowski/WhiteRabbitNeo_WhiteRabbitNeo-V3-7B-GGUF and register local Ollama models WhiteRabbitNeo, WhiteRabbitNeo-Q4, WhiteRabbitNeo-Q8, and WhiteRabbitNeo-IQ2.
Unsloth homes are redirected into this project's state/ tree via symlinks.
Managed web services bind for access from both Linux and the Windows side of WSL, while labctl urls still reports localhost-friendly URLs.
The local Ansible bootstrap in .venv-ansible/ is machine-specific and will be recreated automatically if the folder is copied between hosts.
llama.cpp uses a conservative, memory-aware build parallelism setting instead of an unbounded -j build, which avoids OOM failures on smaller Linux and WSL hosts.

Lab URLs

After ./deploy-courseware.sh, run ./labctl urls.

Default endpoints:

Ollama API: http://127.0.0.1:11434
Open WebUI: http://127.0.0.1:8080
Netron: http://127.0.0.1:8338
ChunkViz: http://127.0.0.1:3001
Embedding Atlas: http://127.0.0.1:5055
Unsloth Studio: http://127.0.0.1:8888
Promptfoo UI: http://127.0.0.1:15500
Wiki: http://127.0.0.1:80
Lab 3 Terminal: http://127.0.0.1:7681/wetty

Lab 3 Browser Terminal

The deployment will:

bind sshd to 127.0.0.1:22 only
install WeTTY and expose it at http://127.0.0.1:7681/wetty
leave login identity management to the host, so any existing local account with password-based SSH access can sign in through the browser terminal

Notes

./labctl up installs the environment and then starts every managed service.
./labctl versions shows the pinned Netron version, minimum Ollama version, and Ansible runtime version used by this workspace.
./labctl assets lab2 is a separate manual step that clones the base WhiteRabbitNeo repo into assets/lab2/WhiteRabbitNeo-V3-7B and downloads the supported Q4_K_M, Q8_0, and IQ2_M GGUFs into assets/lab2/WhiteRabbitNeo_WhiteRabbitNeo-V3-7B-GGUF.
./labctl start core starts only ollama and open-webui.
./labctl start all starts every managed web service.
./labctl open kiln launches the Kiln desktop app installed into the project state.
The scripted Promptfoo install drops a starter config at state/lab6/promptfoo.yaml.
labctl start all includes Promptfoo via promptfoo view and the cloned wiki app.
Lab 2 includes state/lab2/download_whiterabbitneo-gguf.sh, which uses git + git lfs to pull only the supported WhiteRabbitNeo quants. Add --download-only if you want the files without Ollama registration.
The wiki is cloned from https://git.zuccaro.me/bzuccaro/LLM-Labs.git into state/repos/LLM-Labs and started with npm.
./labctl down uninstalls Ollama entirely when this project installed it, instead of only stopping the service.
Unsloth Studio currently supports chat and data workflows on macOS; Linux/WSL remains the standard path for NVIDIA-backed training.