📦
apkg Tutorial
Learn Gentoo package management the easy way
Gentoo Linux v0.5.2 Binhost Mode
The Teaching Philosophy
Every command apkg runs is explained. You'll learn Gentoo while getting work done.
emerge -uDN --getbinpkg --usepkgonly @world → Updates all packages using only binary packages from binhost 1
Welcome to apkg
Argo Package Manager for Gentoo
apkg is a command-line package manager that teaches you Gentoo while simplifying complex operations.
Unlike traditional package managers that hide complexity, apkg shows you every emerge command it runs and explains why.
$ apkg --version
apkg v0.5.2 - Argo Package Manager Mode: binhost (connected to build swarm) Gentoo Linux | Kernel 6.12.10
2
Searching for Packages
Find what you need
apkg uses fuzzy matching to find packages. Just type part of the name and it will find relevant matches.
$ apkg search firefox
🔍 Searching for: firefox
📦 Found 5 packages:
www-client/firefox [installed: 134.0]
Mozilla's flagship web browser
www-client/firefox-bin [available]
Pre-built Firefox binary
x11-plugins/firefox-addons [available]
Firefox addon tools
www-plugins/firefox-gmp [installed: 1.0]
Gecko Media Plugin support
💡 Tip: Use 'apkg info <package>' for details 3
Installing Packages
Binary-first workflow
In binhost mode, apkg fetches pre-compiled binary packages from your build swarm - no local compilation needed.
Watch how apkg explains the underlying emerge command:
$ apkg install htop
📦 Installing: sys-process/htop ┌─ Command: emerge --ask --getbinpkg --usepkgonly sys-process/htop └─ Why: --getbinpkg: Fetch binary from binhost (10.42.0.194) --usepkgonly: NEVER compile locally (binhost mode safety) --ask: Confirm before proceeding 🔗 Fetching from binhost... ✓ sys-process/htop-3.3.0.tbz2 (248 KB) >>> Installing sys-process/htop-3.3.0 >>> Completed in 2.3 seconds ✅ sys-process/htop installed successfully! 📖 Learning Summary: The command you learned: emerge --getbinpkg --usepkgonly sys-process/htop
4
System Health Check
Pre-update diagnostics
Before any major update, run
apkg doctor to check your system's health and catch issues early. $ apkg doctor
🏥 Running System Health Check... Binhost Connection ✓ Binhost online (10.42.0.194) ✓ SSH key authenticated ✓ Last sync: 2 hours ago Portage Status ✓ Tree in sync with binhost ✓ 847 packages installed ✓ No config files pending Disk Space ✓ Root: 45GB free (78%) ✓ /var/cache/binpkgs: 12GB used Dependencies ✓ No broken packages ✓ No circular deps detected 🎉 System is healthy! Safe to update.
5
System Updates
Keep your system current
apkg handles @world updates safely. Use
--pretend to preview changes before applying. $ apkg update --pretend
🔄 Checking for updates... ┌─ Command: emerge -uDNp --getbinpkg --usepkgonly @world └─ Why: -u: Update packages -D: Deep (include dependencies) -N: Rebuild for USE changes -p: Pretend (preview only) 📋 Updates available: [U] sys-libs/glibc-2.39 → 2.40 [U] dev-lang/python-3.12.1 → 3.12.2 [U] kde-plasma/plasma-desktop-6.0.0 → 6.0.1 [N] dev-libs/openssl-3.2.1 (new dependency) Total: 4 packages, 847 MB download 💡 Run 'apkg update' to install these updates.
6
Build Swarm Integration
Distributed compilation power
apkg integrates with the Argo OS Build Swarm for distributed package compilation. Monitor builds in real-time.
$ apkg builds
🔥 Active Builds on Swarm Gateway: 10.42.0.199 (online) Orchestrator: orchestrator-io (primary) Drones: 🟢 drone-Izar 16 cores building: dev-qt/qtcore 🟢 drone-Tau-Beta 8 cores building: media-libs/mesa 🟢 drone-Capella 8 cores idle (sweeper) 🟢 drone-Tarn 14 cores building: sys-devel/gcc 🟡 drone-Meridian 24 cores offline Queue: 12 packages | Building: 3 | Completed: 47 📊 Today: 89 packages built | Speedup: 12.5x vs single machine
7
Nix Integration (Optional)
Hybrid package management
apkg can route userland applications to Nix while keeping system packages on Gentoo - best of both worlds.
$ apkg which firefox
📍 Package Routing: www-client/firefox Classification: USERLAND (user application) Mapping: firefox → nixpkgs.firefox Recommended: Install via Nix/Home Manager ✓ Declarative configuration ✓ Instant rollbacks ✓ No compilation needed Alternative: Install via Gentoo ⚠ Compile time: ~45 min ⚠ Updates require recompilation 💡 Run 'apkg install firefox --nix' to use Nix or 'apkg install firefox --gentoo' for Gentoo
Practice Challenges
Complete these challenges as you work through the tutorial
Challenges
Follow along with the tutorial basics
Install, update, and manage packages
Learn the Gentoo commands that apkg wraps
Understand binary package distribution
Use both Gentoo and Nix with apkg
Diagnose and fix common issues
0% Complete
Quick Reference
apkg install <pkg> Install a package apkg uninstall <pkg> Remove a package apkg search <term> Search packages apkg info <pkg> Package details apkg update Install system updates apkg doctor System health check apkg builds View swarm builds apkg monitor <pkg> Watch a build apkg which <pkg> Check routing (Gentoo/Nix) apkg clean System cleanup Key Concepts
Binhost Mode
Use a dedicated build server for fast binary-only updates. No local compilation needed.
Standard Mode
Traditional compile-from-source Gentoo. Works offline, maximum flexibility.
@world
The set of all explicitly installed packages. Updated with: emerge -uDN @world
Nix Hybrid
Optional Nix integration for userland apps while keeping system packages on Gentoo.