ArgoBox
ArgoBox Infrastructure & Automation
Back to Playground
📦

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.

Terminal
$ 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.
Terminal
$ 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:

Terminal
$ apkg install htop 
📦 Installing: sys-process/htop

┌─ Command: emerge --ask --getbinpkg --usepkgonly sys-process/htop
└─ Why:
   --getbinpkg: Fetch binary from binhost (10.0.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.
Terminal
$ apkg doctor 
🏥 Running System Health Check...

Binhost Connection
  ✓ Binhost online (10.0.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.
Terminal
$ 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.
Terminal
$ apkg builds 
🔥 Active Builds on Swarm

Gateway: 10.0.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.
Terminal
$ 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
View Source Code →

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.

Try It Yourself

💻
Source Code View on Gitea
🔥
Build Swarm See it in action
📖
Deep Dive Full documentation