Skip to content

docs: align Gemma 4 provisioning guidance with hotfix #275 #469

Description

Why this needs follow-through

#275 fixed the blank-spinner / 30-minute timeout failure, but the user-facing docs still do not explain the changed behaviour or how to distinguish normal provisioning from a failure.

Also, please use the shipped name consistently: this is Gemma 4 E2B Q4_0 on the llama.cpp lane, not “Gemma 3”.

Current, verified behaviour

  • The default local model is Gemma 4 E2B Q4_0, downloaded from google/gemma-4-E2B-it-qat-q4_0-gguf (about 3.1 GB).
  • On a cold ClawBox Connect, provisioning may compile llama.cpp with CUDA and download the GGUF. It is therefore variable and may run for much longer than a few minutes.
  • The systemd ceiling is now 2 hours. It is a safety limit, not an expected wait time.
  • The Local AI wizard now starts provisioning asynchronously, shows live journal-tail detail, and reports a systemd failure as soon as the unit enters failed; it should no longer leave the user at a silent spinner.
  • The in-app updater re-delivers systemd unit files, so an already-installed box must complete System Update before retrying local AI.

Documentation changes requested

Add a short “Local AI / Gemma 4 provisioning” section to Choose Your AI Provider, linked from AI Providers, with this user guidance:

Before retrying: install the latest update from Settings → System Update, let the box reboot, then return to Settings → AI Provider → Local AI and enable/retry llama.cpp.

What you should see: a changing detail line while ClawBox prepares llama.cpp and downloads Gemma 4. The first install time depends on connection speed and whether the local runtime needs building; do not promise a fixed “couple of minutes.”

When it has failed: an explicit error/detail is a failed provisioning, not normal progress. Retry only after the update has completed. For support, include the displayed error and, if using SSH, the last journal lines:

journalctl -u 'clawbox-root-update@llamacpp_install.service' -n 100 --no-pager

Update the local-model wording in ClawBox Connect and Hardware Requirements so it does not imply 1–4B is the only realistic local option while the product ships Gemma 4 E2B Q4_0 as the recommended llama.cpp model.

Acceptance criteria

  • No public/user-facing reference calls this hotfix or its shipped model “Gemma 3”.
  • No user guidance gives a fixed short completion promise.
  • Existing-device users are told to update before retrying.
  • Users are told that changing live detail is normal; a surfaced failure detail is actionable.
  • The support command matches the actual provisioning unit.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions