Improve Linux init: apt install and minimal profile optimization by kovtcharov · Pull Request #302 · amd/gaia

kovtcharov · 2026-02-04T19:10:14Z

Summary

Linux Installation Improvements

apt/dpkg install: gaia init now uses apt install ./lemonade-*.deb on Linux for proper dependency resolution
Fix apt 404 errors: Run apt update before install to avoid stale package cache issues
Clean up PATH handling: Remove unnecessary PATH manipulation on Linux (standard paths are already available)

Minimal Profile Optimization

Switch to Qwen3-0.6B: Changed minimal profile from Qwen3-4B-Instruct-2507-GGUF (2.5 GB) to Qwen3-0.6B-GGUF (400 MB)
Updated docs: All references in cli.mdx, quickstart.mdx, installer.mdx reflect new size
Better UX: Added --force-models hint when incomplete downloads are detected

CLI Improvements

Cleaner help output: Removed irrelevant global options from gaia init -h (no more --use-claude, --model, --trace, etc.)
Conditional logging: Made logging level setup conditional to support commands without parent_parser

CPU-only PyTorch (unchanged)

Linux guidance: Added --extra-index-url https://download.pytorch.org/whl/cpu to all doc install commands to avoid ~2GB CUDA deps

Test plan

gaia init --profile minimal installs Qwen3-0.6B (400 MB) via apt on Linux
Windows MSI install still works
Unit tests pass: python -m pytest tests/unit/test_init_command.py
gaia init -h shows only relevant options (no global params)
Incomplete download shows --force-models hint

🤖 Generated with Claude Code

Replace dpkg-based Linux installation with snap in `gaia init`. Linux now uses `sudo snap install lemonade-server --channel {version}/stable` instead of downloading and installing a .deb package. This removes the download step on Linux since snap handles it internally. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Update DEFAULT_MODEL_NAME and all references across source code, documentation, tests, and agent configs (17 files, 33 occurrences). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

The SD agent module existed on disk but was not listed in the packages array, causing ModuleNotFoundError when running `gaia sd` commands.

Catch remaining display names, model keys, and documentation references missed in the initial rename pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Adds https://download.pytorch.org/whl/cpu to all pip/uv install commands that pull [talk] or [rag] extras in docs. Prevents downloading ~2.5GB of unnecessary CUDA dependencies since Whisper runs on CPU. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Updates documentation to guide Linux users to install CPU-only PyTorch to avoid unnecessary CUDA packages (~2GB vs ~200MB), since GAIA's base dependencies (transformers, accelerate) pull in PyTorch. - Add warnings in Linux tabs explaining the need for --extra-index-url - Update basic install commands for Linux to include the CPU-only flag - Separate Linux/WSL and Windows installation instructions in dev.mdx - Keep Windows installation unchanged (doesn't need the flag) Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

When installing Lemonade Server on Linux, stale apt package caches can cause 404 errors because old package versions have been removed from Ubuntu repositories. - Add apt update step before apt install in lemonade_installer.py - Add troubleshooting documentation for 404 errors - Continue installation even if apt update fails (non-blocking) Fixes the common "E: Failed to fetch ... 404 Not Found" error. Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

- Add encoding parameter to open() call - Mark unused variable with underscore

- Change minimal profile model from Qwen3-4B-Instruct-2507-GGUF (2.5 GB) to Qwen3-0.6B-GGUF (400 MB) - Update size references across all documentation (cli.mdx, quickstart.mdx, installer.mdx) - Add --force-models suggestion in incomplete download prompt for users who want to redownload from scratch - Remove irrelevant global parameters from gaia init -h help output (--use-claude, --model, --trace, etc.) - Make logging level setup conditional to support commands without parent_parser - Update test to verify Qwen3-0.6B-GGUF model Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

- Auto-set GGML_VULKAN_DISABLE=1 when starting Lemonade on Linux - Update manual start instructions to include the env var - Prevents "ggml_vulkan: No devices found" errors on WSL - Graceful fallback to CPU mode when GPU drivers are unavailable Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

- Standard paths (/usr/bin, /usr/local/bin) are always in PATH - Overly defensive code that tries to fix a non-existent problem - Simplifies Linux code path to just return early Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

This reverts commit 7bd2964.

- Use dict comprehension for cleaner /etc/os-release parsing - Remove verbose nested try/except blocks - Simplify error messages - 17 fewer lines, same functionality Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

kovtcharov · 2026-02-04T23:44:40Z

@claude review this PR.

github-actions · 2026-02-04T23:45:16Z

Claude finished @kovtcharov's task —— View job

PR Review Complete

Read PR diff and changed files
Review Linux installation improvements
Review minimal profile optimization
Review CLI improvements
Check for security issues
Provide final review summary

Review Summary

Overall: Approved - This is a well-structured PR that significantly improves the Linux installation experience and optimizes the minimal profile for faster onboarding.

Highlights

Linux Installation (lemonade_installer.py:524-614)

🟢 Good: Switching from dpkg -i to apt install properly resolves dependencies automatically
🟢 Good: Running apt update before install prevents stale cache 404 errors
🟢 Good: Linux version check (_check_linux_version) validates Ubuntu 24.04+/Debian 13+ compatibility
🟢 Good: _add_dpkg_binary_to_path() discovers and adds the installed binary location to PATH

Minimal Profile Optimization

🟢 Good: Switching from Qwen3-4B (2.5 GB) to Qwen3-0.6B (400 MB) dramatically reduces initial download
🟢 Good: All documentation consistently updated with new model and size

CLI Improvements (cli.py:2084-2138)

🟢 Good: Removing parent_parser from init command hides irrelevant global options (--use-claude, --model, --trace)
🟢 Good: Conditional logging_level check (line 2196) handles commands without the global argument

Minor Suggestions (Non-blocking)

setup.py lines 73-74: Two new packages added (gaia.agents.sd, gaia.sd) - these appear to be for a new stable diffusion feature. Consider documenting this or adding in a separate PR if it's unrelated to the Linux init changes.
lemonade_client.py line 420-425: The --force-models hint in the repair prompt is helpful - good UX improvement for users with incomplete downloads.

Security Review

✅ No hardcoded credentials or secrets
✅ subprocess.run uses proper argument lists (no shell injection)
✅ Timeout limits on all subprocess calls (120s for apt update, 300s for install)
✅ No user input is passed unsanitized to shell commands

Documentation

All 19 documentation files updated consistently - model references, size estimates, and install commands all properly reflect the changes.

- dpkg installs to standard locations already in PATH - No need to query dpkg and manually add directories - Removes debugging code that shouldn't be in production Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

Patch release for Linux init improvements Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

kovtcharov and others added 2 commits February 4, 2026 11:00

kovtcharov requested a review from kovtcharov-amd as a code owner February 4, 2026 19:10

Add missing gaia.sd and gaia.agents.sd packages to setup.py

4bec578

The SD agent module existed on disk but was not listed in the packages array, causing ModuleNotFoundError when running `gaia sd` commands.

github-actions bot added documentation Documentation changes devops DevOps/infrastructure changes llm LLM backend changes tests Test changes performance Performance-critical changes dependencies Dependency updates labels Feb 4, 2026

kovtcharov self-assigned this Feb 4, 2026

kovtcharov and others added 7 commits February 4, 2026 11:20

cpu only for pytorch

5c1c089

Fix Pylint errors in lemonade_installer.py

b6ae843

- Add encoding parameter to open() call - Mark unused variable with underscore

github-actions bot added the cli CLI changes label Feb 4, 2026

kovtcharov-amd approved these changes Feb 4, 2026

View reviewed changes

kovtcharov changed the title ~~Add Linux snap support and update default model to Qwen3-0.6B-GGUF~~ Improve Linux init: apt install, minimal profile 0.6B, auto-disable Vulkan Feb 4, 2026

kovtcharov and others added 2 commits February 4, 2026 15:35

Revert "Add automatic Vulkan disabling for Linux/WSL in gaia init"

9bfed60

This reverts commit 7bd2964.

kovtcharov changed the title ~~Improve Linux init: apt install, minimal profile 0.6B, auto-disable Vulkan~~ Improve Linux init: apt install and minimal profile optimization Feb 4, 2026

Simplify Linux version check function

f241ee1

- Use dict comprehension for cleaner /etc/os-release parsing - Remove verbose nested try/except blocks - Simplify error messages - 17 fewer lines, same functionality Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

kovtcharov and others added 2 commits February 4, 2026 15:47

Remove unnecessary dpkg PATH manipulation

feb43a7

- dpkg installs to standard locations already in PATH - No need to query dpkg and manually add directories - Removes debugging code that shouldn't be in production Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

Bump version to 0.15.3.1

313382b

Patch release for Linux init improvements Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>

kovtcharov enabled auto-merge February 4, 2026 23:49

lint

b86142f

kovtcharov-amd disabled auto-merge February 5, 2026 01:10

kovtcharov-amd merged commit b9cf8ea into main Feb 5, 2026
50 of 51 checks passed

kovtcharov-amd deleted the kalin/gaia-init-linux branch February 5, 2026 01:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Linux init: apt install and minimal profile optimization#302

Improve Linux init: apt install and minimal profile optimization#302
kovtcharov-amd merged 17 commits intomainfrom
kalin/gaia-init-linux

kovtcharov commented Feb 4, 2026 •

edited

Loading

Uh oh!

kovtcharov commented Feb 4, 2026

Uh oh!

github-actions bot commented Feb 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kovtcharov commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Linux Installation Improvements

Minimal Profile Optimization

CLI Improvements

CPU-only PyTorch (unchanged)

Test plan

Uh oh!

kovtcharov commented Feb 4, 2026

Uh oh!

github-actions bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Complete

Review Summary

Highlights

Minor Suggestions (Non-blocking)

Security Review

Documentation

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kovtcharov commented Feb 4, 2026 •

edited

Loading

github-actions bot commented Feb 4, 2026 •

edited

Loading