feat: improve instance creation clarity and live model status

[rwfraser]

Summary

This PR addresses three pain points in the llamactl web UI:

1. Router mode is now explained during instance creation

When creating a llama.cpp instance without specifying a model, hf_repo, or a preset, the Backend tab now shows a blue informational callout explaining that llama-server will start in router mode and may auto-discover cached HF model presets. It lists the three ways to configure a specific model (local path, HF repo+file, or Preset tab), so users are not surprised by unexpected multi-model behaviour.

The callout disappears as soon as any of those fields are filled in.

2. Instance card shows live model status

The instance card now polls model state every 10 seconds while an instance is running (previously it fetched once on mount and never updated again):

• Single-model instance: shows the loaded model's id/alias as a badge directly on the card.
• Multi-model / router instance: keeps the existing X/N models count badge, but it now stays current after load/unload operations without a manual page refresh.
• Models dialog: fires a callback immediately after any load or unload action so the card badge refreshes at once, not just when the next poll fires.

3. Field labels, descriptions, and tooltips improved

• hf_repo placeholder changed from microsoft/DialoGPT-medium (a vLLM example) to ggml-org/gemma-3-1b-it-GGUF, which is a GGUF repository.
• hf_file added as a basic llama.cpp field with an example filename.
• model, hf_repo, hf_file, gpu_layers, and models_preset all received expanded descriptions and tooltip text (shown via a small ? icon next to the label).
• Fixed merge order in basicBackendFieldsConfig so llama.cpp field metadata takes precedence over the vLLM config for shared keys such as model.
• GeneralTab: expanded descriptions for instance name, group, idle timeout, and on-demand start fields.

Tests

All 68 frontend tests pass (npm run test:run), type-check is clean (npm run type-check), and the build completes without errors (npm run build).

New test coverage added:

• InstanceCard: single-model badge display, multi-model badge display, no badge on stopped instance, polling interval setup.
• InstanceModal: router mode callout shows on Backend tab when no model is set; callout absent when editing an instance that already has a model configured.

Testing context

These changes were developed and tested against a local llamactl instance running two llama.cpp instances (a router-mode instance serving 6 cached models, and a direct Qwen3.6-35B instance).

---

Note: This replaces PR #224, which was closed because unrelated commits had been pushed to that branch after the PR was opened. This branch contains only the changes described above.

Co-Authored-By: Oz oz-agent@warp.dev

[lordmathis]

Thanks for the PR! I like the improvements but there are few issues to address.

1. I think the router mode callout is quite loud and could be disruptive. It could be just the headline - "No model specified — router mode will be used" and then could be expanded with the full explanation on click.
2. For field labels, placeholders and tooltips - the issue here is that these are not currently backend specific and the info leaks between the backends. This is visible for shared fields such as model. Previously for llama.cpp backend it showed vLLM model just because it was the last backend in the list. Your change just switches this to llama.cpp so now the placeholder and tooltip show gguf model info for all backends. The fix is to make the lookup backend-aware. backendFieldConfigs (zodFormUtils.ts:137) is already a per-backend map keyed by 'llama_cpp' | 'mlx_lm' | 'vllm' (same values as BackendType) — it just isn't exported. BackendFormField already receives formData (which has backend_type), so look up backendFieldConfigs[backend_type]?.[fieldKey] first, falling back to the merged basicBackendFieldsConfig.
3. Related to the 2. point, there is a models_preset branch in BackendFormField.tsx:40 — it hardcodes its text and bypasses the config, so its new tooltip never renders.

[rwfraser]

Great feedback. I realized my gguf-centredness a bit belatedly, but had come to the same coclusion - let's make the lookup backend aware. I will work on these as time allows and respond. For fun, I have implemented a chat front-end on loaded models, but I am not really sure this is desirable for the user base, it seems it is not really its purpose. However, I may expand it to a rag which might make its presence on the front of the dashboard a bit more useful. Your thoughts on this are welcome. best wishes!

On 2026-07-16 17:51, Matúš Námešný wrote: lordmathis left a comment (lordmathis/llamactl#225) [1] Thanks for the PR! I like the improvements but there are few issues to address. * I think the router mode callout is quite loud and could be disruptive. It could be just the headline - "No model specified -- router mode will be used" and then could be expanded with the full explanation on click. * For field labels, placeholders and tooltips - the issue here is that these are not currently backend specific and the info leaks between the backends. This is visible for shared fields such as model. Previously for llama.cpp backend it showed vLLM model just because it was the last backend in the list. Your change just switches this to llama.cpp so now the placeholder and tooltip show gguf model info for all backends. The fix is to make the lookup backend-aware. backendFieldConfigs (zodFormUtils.ts:137) is already a per-backend map keyed by 'llama_cpp' | 'mlx_lm' | 'vllm' (same values as BackendType) -- it just isn't exported. BackendFormField already receives formData (which has backend_type), so look up backendFieldConfigs[backend_type]?.[fieldKey] first, falling back to the merged basicBackendFieldsConfig. * Related to the 2. point, there is a models_preset branch in BackendFormField.tsx:40 -- it hardcodes its text and bypasses the config, so its new tooltip never renders. -- Reply to this email directly, view it on GitHub [2], or unsubscribe [3]. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS [4] and Android [5]. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

Links: ------ [1] #225 (comment) [2] #225?email_source=notifications&email_token=AYMSEE2HUVCSLHSVZLNAVDD5FEIYLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOJZGQ4TMMZUHA3KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4994963486 [3] https://github.com/notifications/unsubscribe-auth/AYMSEE4KQ3A2MB2WSTYDA2D5FEIYLAVCNFSNUABGKJSXA33TNF2G64TZHMYTAMRQHE4TOMRRGM5US43TOVSTWNBYHA2TMMBTG43TNILWAI [4] https://github.com/notifications/mobile/ios/AYMSEEZCP2HEDZFYZLREHVD5FEIYLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOJZGQ4TMMZUHA3KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG [5] https://github.com/notifications/mobile/android/AYMSEEYLJKR2W5IH7BBVQUT5FEIYLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOJZGQ4TMMZUHA3KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA