Host runtimes (`requires_runtime`)

A plugin needs a native runtime (llama.cpp, some inference backend, a set of DLLs) to work, but that thing is tens of MB or more — packing it into the .tbmod both fails the upload channel (20 MB limit) and makes every subscriber re-download it on every update.
The host ships on-demand runtime components (download + sha256 verification + extraction, with resume / pause / disk-full pre-check); the plugin only declares which one it needs.

Declaration

json

{
  "requires_runtime": [
    { "id": "llama_runtime", "reason": "提供 llama.cpp 运行时（llama-server + Vulkan/CPU 后端）" }
  ]
}

Item	Notes
Count	≤ 4 (extras are dropped); the shorthand `["llama_runtime"]` is equivalent to the object form
`id`	A runtime id the host knows (see the table below); an unknown id counts as unmet and tells the user "upgrade TransBox to get support"
`reason`	Optional; one sentence meant for humans (may be shown on the card / in a hint)

Runtimes the host knows

id	Contents	Used for	On-disk location
`llama_runtime`	llama.cpp runtime (`llama-server.exe` + Vulkan/CPU backends)	Text translation (MT) / multimodal ASR	`data/local-runtime/runtimes/llama-vulkan/`
`whisper_runtime`	whisper.cpp runtime (`whisper-server.exe` + Vulkan/CPU backends)	Local speech recognition (ASR)	`data/local-runtime/runtimes/whisper-vulkan/`
`audiocpp_runtime`	audio.cpp runtime (`audiocpp_server.exe` + Vulkan/CPU backends + eSpeak-NG)	Local speech synthesis (TTS)	`data/local-runtime/runtimes/audiocpp/`
`tts_server_runtime`	qwentts.cpp's `tts-server.exe` (Qwen3-TTS specific; OpenAI-compatible `/v1/audio/speech` + a clone-voice registry)	Local speech synthesis (TTS, Qwen3-TTS family)	`data/local-runtime/runtimes/tts-server/`
`nv_pack_cu13`	NVIDIA-only acceleration pack (CUDA 13.3 tuned; bundles llama + whisper + audiocpp and the shared CUDA DLLs)	NVIDIA users speeding up every local model	`data/local-runtime/runtimes/nv-pack-cu13/`

What bundled means: llama_runtime / whisper_runtime / audiocpp_runtime / tts_server_runtime are all bundled with the installer (bundled=True) — users never see a Download runtime button. Declaring them only makes the host run a readiness check (with a clear message when files are missing); no download flow is involved. The full HTTP contract for tts-server is in Local TTS service (tts_server_runtime).

Host behaviour

It shares the same gate as requires_plugins:

While a runtime is not ready: enabling the plugin is refused, selecting it as the ASR/MT/TTS engine is refused, and starting simultaneous interpretation is blocked with missing_dependency;
For runtimes that are not bundled, the message reads "Runtime required: llama.cpp runtime (not downloaded)" and the plugin card button becomes Download runtime; bundled runtimes have no download path at all — a failure is reported as an incomplete installation;
For non-bundled runtimes the host does the download → sha256 verification → extraction itself (pausable / resumable / retryable / disk-full pre-check); once it finishes the runtime is ready, and enabling works on the next click;
The dependency chain applies here too (see Prerequisite plugins).

A plugin must not download, unpack or bundle this binary itself, and must not list it in model_artifacts.

Using it

python

from pathlib import Path

runtime = self.host.runtime_dir("llama_runtime")     # returns "" when not downloaded
if not runtime or not self.host.has_runtime("llama_runtime"):
    return False, "model_not_ready", "需要先下载「llama.cpp 运行库」（「运行组件」窗口或插件卡片按钮）"

exe = Path(runtime) / "llama-server.exe"

You do not need to know which plugin carries the runtime.

A bundled runtime (bundled=True) is already inside the installer, so runtime_dir() returns the directory directly. A failure to locate it means the installation is incomplete — tell the user to reinstall; never point them at "Download runtime".

Compatibility note: the bundled workshop.common_llama plugin still ships that runtime in its original layout, so the old form host.plugin_dir("workshop.common_llama") / "llama" / "llama-server.exe" works as well — both paths point at the same files, no change needed.

`requires_runtime` vs `model_artifacts`

	`requires_runtime`	`model_artifacts`
What gets installed	Native binaries / runtime (exe/dll)	Model weights (safetensors/gguf…)
Source	Official CDN	Hugging Face / ModelScope / hf-mirror
On disk	Inside the plugin directory (decided by the runtime component)	`<data dir>/models/<...>`
User-visible	"Run components" window / card "Download runtime"	Settings model card (mirror / proxy / progress / clear cache)
Plugin access	`host.runtime_dir(id)`	`inspect_model_artifact()["target_dir"]`

Host runtimes (requires_runtime) ​

Declaration ​

Runtimes the host knows ​

Host behaviour ​

Using it ​

requires_runtime vs model_artifacts ​