fix: name a local GGUF with --model instead of trying to resolve it

[michaelneale]

You can now give a local GGUF a friendly name:

mesh-llm serve --mesh-name MainMesh \
  --model deepseek-v4-flash \
  --gguf /models/UD-IQ3_S/DeepSeek-V4-Flash-UD-IQ3_S-00001-of-00004.gguf

deepseek-v4-flash becomes the served model name — in /v1/models, in the console, and in "model": "deepseek-v4-flash" request bodies — rather than being looked up on Hugging Face and failing startup:

ERR Model not found: deepseek-v4-flash (Not a local file, not in Hugging Face cache, not in catalog).
Eager startup model 'deepseek-v4-flash' failed to resolve after daemon surfaces became ready.

Fixes #1254. Reported by @hola-there, who also identified the correct behaviour and the --model-less workaround.

Scope

The alias binding only applies to the unambiguous naming form: exactly one --gguf and exactly one --model whose value is a plain name — no /, \, :, or @, and not an existing path. Anything that could resolve on its own (unsloth/Qwen3-8B-GGUF:Q4_K_M, a second local path, a URL) still starts as its own model, so multi-model serve is unchanged.

Validation

• cargo test -p mesh-llm-host-runtime --lib — 2454 passed, 0 failed
• cargo clippy -p mesh-llm-host-runtime --all-targets -- -D warnings — clean
• cargo clippy -p mesh-llm --all-targets -- -D warnings — clean
• cargo fmt --all --check — clean

Three new tests in runtime/tests/startup_models.rs cover the alias binding, the HF-ref case that must stay two models, and end-to-end resolution proving the alias no longer reaches the catalog.

Summary by CodeRabbit

• New Features

  • Added support for starting local GGUF models with a custom model alias.
  • Local model aliases are preserved in the startup configuration and do not require external catalog lookup.
  • Existing projector and context-size settings remain intact when loading local models.

• Bug Fixes

  • Improved validation for GGUF file paths and model identifiers.
  • Prevented valid Hugging Face model references from being incorrectly replaced during startup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ac092c5c-ecc3-4167-b7a5-8ccdf908fb5f

📥 Commits

Reviewing files that changed from the base of the PR and between 602eae7 and 6c77a8a.

📒 Files selected for processing (2)

• crates/mesh-llm-host-runtime/src/runtime/startup_models.rs
• crates/mesh-llm-host-runtime/src/runtime/tests/startup_models.rs

---

📝 Walkthrough

Walkthrough

The runtime now accepts --gguf <path> --model <alias> as one local GGUF startup model. It validates the file, preserves configuration, avoids alias catalog lookup, and adds coverage for local and Hugging Face model combinations.

Changes

Local GGUF alias handling

Layer / File(s)	Summary
Detect and build local GGUF aliases crates/mesh-llm-host-runtime/src/runtime/startup_models.rs	The parser stores --gguf values. Startup construction recognizes valid plain aliases, validates the GGUF file, and preserves the alias, projector, and context size.
Resolve and validate local GGUF aliases crates/mesh-llm-host-runtime/src/runtime/tests/startup_models.rs	Tests verify one local aliased startup model, retention of a separate Hugging Face model, and direct local alias resolution without catalog lookup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: ⚪ Minimal · up to 6c77a

The change gives an explicitly named local GGUF a stable served model name while preserving existing multi-model resolution behavior; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant StartupModelBuilder
  participant GGUFResolver
  CLI->>StartupModelBuilder: provide --gguf path and --model alias
  StartupModelBuilder->>GGUFResolver: resolve local GGUF path
  GGUFResolver-->>StartupModelBuilder: return local model identity
  StartupModelBuilder-->>CLI: expose one startup model with declared alias

Loading

Possibly related PRs

• Mesh-LLM/mesh-llm#1148: Both changes update startup_models.rs for local GGUF parsing and alias resolution.

Suggested reviewers: ndizazzo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the alias behavior required by issue #1254 and add tests for local GGUF alias resolution.
Out of Scope Changes check	✅ Passed	The code and tests remain within the linked issue scope of local GGUF model alias handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: assigning a friendly name to a local GGUF file with --model.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/gguf-model-alias

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}