apkg
Argo Package Manager
Dual-mode Gentoo + Nix package management with Build Swarm integration
Quick Start
Why apkg?
Traditional Gentoo
emerge --ask --verbose --update --deep --newuse @world - Long, hard to remember commands
- Compiles everything from source
- Hours/days of compilation time
- Complex USE flag management
With apkg
apkg upgrade - Simple, intuitive commands
- Uses binary packages from Build Swarm
- Updates in minutes, not hours
- Automatic binhost configuration
- Smart Gentoo/Nix routing for every package
Architecture
apkg acts as a decision engine that routes each package to the optimal backend based on its classification.
Nix Integration
Starting with v0.5.0, apkg operates in dual-mode: system packages go to Gentoo, userland applications route to Nix. The best of both worlds.
Smart Classification
Every package is classified into one of two categories based on 70+ pre-configured mappings and heuristic rules:
System Packages → Gentoo
- Kernel and modules
- GPU drivers (nvidia, mesa)
- System libraries (glibc, openssl)
- Init system (OpenRC)
- Bootloader (GRUB)
- Low-level toolchain (gcc, binutils)
Userland Apps → Nix
- Web browsers (Firefox, Chromium)
- Editors (VS Code, Neovim)
- Communication (Discord, Slack)
- Media (Spotify, VLC, OBS)
- Dev tools (Node.js, Go, Rust tools)
- CLI utilities (ripgrep, fd, bat)
Override Controls
Force a package to a specific backend when you know better than the heuristics:
apkg install --nix firefox # Force Nix backend apkg install --gentoo firefox # Force Gentoo/emerge Persistent overrides can be set in the config file with NIX_FORCE_GENTOO and NIX_FORCE_NIX variables.
Nix Backend Modes
apkg supports two Nix management strategies:
Terminal Output Examples
apkg produces educational, color-coded output that explains what is happening under the hood.
Features
Binary Package First
Automatically fetches pre-compiled packages from the Build Swarm binhost when available.
Smart Search
Fuzzy search across package names and descriptions with highlighted results.
Status Dashboard
View installed packages, pending updates, and system health at a glance.
USE Flag Helper
Interactive USE flag selection with descriptions and dependency info.
Swarm Integration
Request builds from the Build Swarm if a package isn't in the binhost yet.
Beautiful Output
Color-coded, human-readable output with progress bars and status indicators.
Dual-Mode Routing
Smart decision engine routes each package to Gentoo or Nix based on 70+ mappings.
Health Checks
Built-in doctor command validates binhost, Nix daemon, portage tree, and library links.
Build Swarm Integration
apkg is the client-side interface to the Argo OS Build Swarm. Here is how packages flow from compilation to your machine.
Build Swarm Compiles
66 cores across 5 drones compile packages in parallel with your USE flags
Binhost Hosts
Binary packages stored on the binhost, ready for instant download
apkg Fetches
apkg pulls binaries instead of compiling locally. Zero CPU burn.
30-Second Installs
What took 45 minutes from source now takes half a minute from binary
Command Reference
| Command | Description | Equivalent emerge |
|---|---|---|
apkg install <pkg> | Install a package (auto-routes to Gentoo or Nix) | emerge --ask pkg |
apkg remove <pkg> | Uninstall a package | emerge --ask --depclean pkg |
apkg search <term> | Search for packages | emerge --search term |
apkg update | Sync repos & show updates | emerge --sync && emerge -pvuDN @world |
apkg upgrade | Apply all updates | emerge -uDN @world |
apkg info <pkg> | Show package details | equery meta pkg |
apkg clean | Remove orphan packages | emerge --depclean |
apkg status | System status dashboard | No equivalent |
apkg doctor | Pre-update health checks | No equivalent |
apkg which <pkg> | Shows routing decision (Gentoo vs Nix) | No equivalent |
apkg binhost <addr> | Quick binhost switcher | Manual make.conf edit |
apkg sync --both | Sync portage + nix channels | emerge --sync |
Configuration Reference
apkg is configured via /etc/apkg/apkg.conf or environment variables. All settings have sensible defaults.
| Variable | Values | Default | Description |
|---|---|---|---|
APKG_MODE | binhost, standard, auto | auto | Package fetch strategy. auto tries binhost first, falls back to source. |
BINHOST_ADDRESS | IP or hostname | 10.42.0.194:8080 | Address of the Build Swarm binhost server. |
NIX_USERLAND | disabled, nix-env, home-manager, auto | auto | Nix backend mode. auto detects home-manager, falls back to nix-env. |
NIX_FORCE_GENTOO | Comma-separated package list | empty | Always route these packages to Gentoo, overriding classification. |
NIX_FORCE_NIX | Comma-separated package list | empty | Always route these packages to Nix, overriding classification. |
Installation
Clone the repository
git clone https://github.com/KeyArgo/apkg.git Run the installer
cd apkg && sudo ./install.sh Configure binhost (optional)
apkg config --binhost http://binhost.local:8080 Enable Nix integration (optional)
apkg config --nix auto Verify setup
apkg doctor