Argo OS Experience
Explore a real Gentoo-based environment powered by ArgoBox infrastructure
🌀
Lab Host Resource Status
Checking...This lab runs on ArgoBox's heavy compute infrastructure. A full QEMU virtual machine is provisioned on demand.
Connecting to lab engine...
Checking if real Linux environments are available
Real Container Lab
Launch an ephemeral LXC container for hands-on practice. Auto-destroys after 60 minutes.
Prefer offline mode?
Provisioning a real Linux container on isolated infrastructure
Creating LXC container on Proxmox...
Booting Alpine Linux & installing tools...
Opening live terminal session...
!
Failed to create lab
Connected to live container -- this is a real, isolated Linux environment
Simulation Mode -- Could not reach lab engine. Using client-side sandbox.
Challenges
Navigate the Gentoo package manager
○ Search for a package
- Run emerge --search vim to search the Portage tree for packages matching "vim"
- Each result shows the full category/package name (e.g., app-editors/vim) — Gentoo organizes every package into a category
- Note the description and homepage URL printed for each match
emerge --search vim 💡 Use emerge -s for short form. You can also search descriptions with emerge -S or use eix for faster searches once you know it.
○ View installed packages
- Run qlist -I to list every package installed on this system
- Pipe it through head -20 to see just the first 20 entries
- Each line shows category/package format — this is how Portage tracks what is installed
qlist -I | head -20 💡 qlist is part of app-portage/portage-utils, a set of fast C-based Portage helpers. Try qlist -Iv to include version numbers.
○ Inspect make.conf
- Run cat /etc/portage/make.conf to view the main Portage configuration file
- This file controls global build settings: compiler flags (CFLAGS), USE flags, mirrors, and more
- Look for the MAKEOPTS line — it sets how many parallel compile jobs to run
cat /etc/portage/make.conf 💡 make.conf is the single most important config file in Gentoo. Every emerge command reads it to decide how to build packages.
○ Check installed package version
- Run equery list vim to see which version of Vim is installed
- The output shows the full category/package-version string (e.g., app-editors/vim-9.0.1234)
- You can use wildcard patterns too — try equery list "*kde*" to find all KDE-related packages
equery list vim 💡 equery is part of app-portage/gentoolkit. It is one of the most useful Gentoo tools — run equery without arguments to see all subcommands.
○ Browse the Portage tree
- Run ls /var/db/repos/gentoo to see the top-level categories in the Portage tree
- Each directory is a category (app-editors, sys-apps, dev-libs, etc.) containing related packages
- Pick a category and drill down: ls /var/db/repos/gentoo/app-editors/ to see available packages in that category
ls /var/db/repos/gentoo 💡 The Portage tree at /var/db/repos/gentoo is synced from Gentoo mirrors. Each package directory contains ebuild files — the build recipes that tell Portage how to compile and install software.
Understand the Argo OS build configuration
○ Check compiler flags
- Run grep -E "CFLAGS|CXXFLAGS" /etc/portage/make.conf to see the compiler optimization flags
- CFLAGS controls C compiler flags, CXXFLAGS controls C++ — they usually match
- Look for -march=native (optimize for this CPU), -O2 (optimization level), and -pipe (use pipes instead of temp files)
grep -E "CFLAGS|CXXFLAGS" /etc/portage/make.conf 💡 Gentoo compiles packages from source, so these flags directly affect the generated binaries. -march=native means code is tuned for the exact CPU in this machine.
○ View parallel compile settings
- Run grep MAKEOPTS /etc/portage/make.conf to see the parallel job configuration
- MAKEOPTS="-jN" tells make to run N compile jobs simultaneously
- This is typically set to the number of CPU cores + 1 for maximum throughput
grep MAKEOPTS /etc/portage/make.conf 💡 On a build swarm, MAKEOPTS is tuned per machine. A 16-core drone might use -j17, while a desktop uses fewer jobs to stay responsive.
○ Check the kernel version
- Run uname -r to display the running kernel version string
- The output includes the version number and any local suffix (e.g., -gentoo-dist)
- Try uname -a for full system information including architecture and hostname
uname -r 💡 Gentoo gives you full control over the kernel. The -gentoo suffix means this kernel was built from sys-kernel/gentoo-sources with Gentoo patches applied.
○ View CPU information
- Run cat /proc/cpuinfo | head -20 to see the processor details
- Look for "model name" (the CPU model), "cpu cores" (physical cores), and "cpu MHz" (current clock speed)
- The "flags" line shows CPU feature flags — these determine what -march=native can optimize for
cat /proc/cpuinfo | head -20 💡 The CPU flags matter for Gentoo because source compilation can use CPU-specific instructions (SSE, AVX, etc.) when -march=native is set in CFLAGS.
○ Explore the KDE Plasma desktop
- Switch to the Desktop (GUI) tab above to open the VNC connection
- You should see a full KDE Plasma desktop — right-click the desktop for the context menu
- Open the application launcher (bottom-left) to see what GUI applications are installed
💡 This is a real KDE Plasma session running in the VM. Everything you see was compiled from source via Portage, including the entire Qt/KDE stack.
Understand Gentoo's build customization system
○ View global USE flags
- Run emerge --info | grep USE to see all active global USE flags
- These flags control which features are compiled into every package that supports them
- Common flags include X (X11 support), gtk (GTK toolkit), qt5 (Qt5 toolkit), systemd vs openrc, pulseaudio, bluetooth, etc.
emerge --info | grep USE 💡 USE flags are Gentoo's killer feature. Instead of a one-size-fits-all binary, you choose exactly what features to compile in. No Bluetooth? Disable it globally and every package skips Bluetooth support.
○ Check USE flags for a specific package
- Run equery uses app-editors/vim to see all USE flags available for Vim
- Each line shows a flag name, whether it is enabled (+) or disabled (-), and a description
- Enabled flags mean that feature was compiled in; disabled flags were excluded at build time
equery uses app-editors/vim 💡 Red flags with a minus are disabled; blue/green flags with a plus are enabled. The description explains what each flag actually does to the build.
○ Explore per-package USE flags
- Run ls /etc/portage/package.use/ to see per-package USE flag overrides
- Each file in this directory can override global USE flags for specific packages
- Read one of the files to see the format: category/package flag1 flag2 -flag3 (minus disables a flag)
ls /etc/portage/package.use/ 💡 Global USE flags in make.conf apply everywhere, but sometimes you need a flag only for one package. Per-package USE files let you be surgical about it.
Expected:
A list of files, each containing USE flag overrides for specific packages
○ View the master USE flag descriptions
- Run head -50 /var/db/repos/gentoo/profiles/use.desc to see the first 50 global USE flag descriptions
- Each line defines one global USE flag and what it means across all packages
- There are hundreds of global USE flags — this file is the canonical reference
head -50 /var/db/repos/gentoo/profiles/use.desc 💡 There are also local USE flags defined per-package in use.local.desc. These only apply to specific packages rather than globally.
○ Find packages using a specific USE flag
- Run equery hasuse X to find all installed packages that support the X (X11) USE flag
- The output shows every installed package that recognizes this flag, whether enabled or not
- Try other flags like bluetooth, pulseaudio, or python to see their reach across the system
equery hasuse X 💡 This is useful for understanding the blast radius of a USE flag change. Toggling a common flag like X or dbus could trigger rebuilds of dozens of packages.
Learn about binary package distribution and binhosts
○ Check binhost configuration
- Run grep -i binhost /etc/portage/make.conf to find the PORTAGE_BINHOST setting
- This URL points to a server hosting precompiled binary packages (binpkgs)
- When configured, Portage can download binpkgs instead of compiling from source — much faster
grep -i binhost /etc/portage/make.conf 💡 Argo OS uses a build swarm to compile packages on powerful machines, then distributes the binaries via binhost. Client machines pull prebuilt packages instead of compiling locally.
○ View binary package FEATURES
- Run grep FEATURES /etc/portage/make.conf to see Portage feature flags
- Look for getbinpkg (download binpkgs from binhost) and binpkg-request-signature (verify package signatures)
- Other features like parallel-fetch and candy control Portage behavior during installs
grep FEATURES /etc/portage/make.conf 💡 FEATURES is a space-separated list that tweaks Portage internals. getbinpkg is the key one for binary packages — without it, Portage ignores the binhost entirely.
○ List cached binary packages
- Run ls /var/cache/binpkgs/ to see the binary package cache directory
- Binary packages are organized by category, mirroring the Portage tree structure
- Pick a category and list it to see .gpkg.tar files — these are the actual binary packages
ls /var/cache/binpkgs/ 💡 The .gpkg.tar format (GPKG) replaced the older .tbz2 format. Each archive contains the compiled files, metadata, and optionally a signature for verification.
Expected:
Category directories like app-editors/, sys-libs/, dev-libs/ containing binary packages
○ Understand binary package install modes
- The --usepkg (-k) flag tells emerge to prefer binpkgs but fall back to source compilation if unavailable
- The --usepkgonly (-K) flag tells emerge to ONLY use binpkgs — it will fail if no binary exists
- Try emerge --pretend --usepkg app-editors/vim to see what Portage would do (pretend mode is safe — it only shows the plan)
emerge --pretend --usepkg app-editors/vim 💡 In pretend output, look for [binary] markers next to packages. The letter "B" in the flags column also indicates a binary package install.
○ Check default emerge options
- Run grep EMERGE_DEFAULT_OPTS /etc/portage/make.conf to see default flags passed to every emerge command
- If --usepkg or --getbinpkg appears here, the system defaults to using binary packages
- This is how Argo OS client machines are configured — they always prefer binpkgs without having to type the flag
grep EMERGE_DEFAULT_OPTS /etc/portage/make.conf 💡 EMERGE_DEFAULT_OPTS saves typing. Common additions include --ask (always confirm), --verbose (show USE flags), and --usepkg (prefer binaries).
Control which package versions are available
○ Explore accepted keywords
- Run ls /etc/portage/package.accept_keywords/ to see keyword override files
- Read one of the files — each line unmasks a package for the ~amd64 (testing) keyword
- The format is: category/package ~amd64 — this tells Portage to accept testing versions
ls /etc/portage/package.accept_keywords/ 💡 Gentoo has two stability tiers: stable (amd64) and testing (~amd64). Most systems run stable, but specific packages can be unmasked to get newer versions.
○ Understand stable vs testing keywords
- Run emerge --search firefox to find the browser package and see its available versions
- Stable packages have the amd64 keyword — these are well-tested and recommended
- Testing packages have ~amd64 (note the tilde) — they are newer but may have issues
- You can also check: eix -e www-client/firefox to see all versions and their keywords side by side
emerge --search firefox 💡 The ~ (tilde) prefix means testing. Gentoo developers first mark packages ~amd64, then promote to amd64 after testing. You can live on ~amd64 globally but it is like running a rolling beta.
○ Check package masks
- Run ls /etc/portage/package.mask/ to see locally masked packages
- A masked package is completely hidden from Portage — it will not be installed or upgraded
- Read one of the files to see the format — each line blocks a specific version or version range
ls /etc/portage/package.mask/ 💡 Masks are stronger than keyword restrictions. Use them to block known-broken versions or prevent unwanted major upgrades. The >= operator blocks a version and everything newer.
○ View an ebuild in the Portage tree
- Run ls /var/db/repos/gentoo/app-editors/vim/ to see all available ebuild versions
- Each .ebuild file is a specific version — the filename encodes the version number
- Read one with cat /var/db/repos/gentoo/app-editors/vim/vim-9*.ebuild | head -40 to see the build recipe
ls /var/db/repos/gentoo/app-editors/vim/ 💡 Ebuilds are bash scripts that follow a strict API. Portage calls specific functions (src_prepare, src_configure, src_compile, src_install) in order to build the package.
Expected:
Multiple .ebuild files, a files/ directory, metadata.xml, and a Manifest file
○ Read a package changelog
- Run equery changes app-editors/vim to see the commit history for this package
- Each entry shows who changed the ebuild, when, and why — useful for tracking version bumps
- Look for entries mentioning security fixes, new USE flags, or dependency changes
equery changes app-editors/vim 💡 Changelogs show the human side of package maintenance. Gentoo developers leave notes when they stabilize packages, fix bugs, or update dependencies.
Manage additional package repositories
○ List configured repositories
- Run eselect repository list to see all known Gentoo overlays
- Overlays marked with an asterisk (*) are currently enabled on this system
- Each overlay is a supplementary package tree that can override or extend the main Gentoo repository
eselect repository list 💡 Overlays are community-maintained package trees. Popular ones include guru (community packages), steam-overlay (gaming), and various hardware-specific overlays.
○ Explore repository configuration
- Run ls /etc/portage/repos.conf/ to see repository configuration files
- Read the main file to see how the primary Gentoo repo is configured
- Each repo config specifies a location on disk, sync type (git/rsync), and sync URI
ls /etc/portage/repos.conf/ 💡 The repos.conf directory replaced the old PORTDIR and SYNC variables in make.conf. Each file can define one or more repositories with their sync settings.
○ View main repo sync settings
- Run cat /etc/portage/repos.conf/gentoo.conf to see the main Gentoo repository configuration
- Look for sync-type (rsync or git), sync-uri (the mirror URL), and location (where the tree lives on disk)
- The auto-sync setting controls whether emaint sync -a will update this repo automatically
cat /etc/portage/repos.conf/gentoo.conf 💡 Most Gentoo systems sync via rsync or git. Git syncs pull the full tree history but are more bandwidth-efficient for incremental updates. The default location is /var/db/repos/gentoo.
○ Understand overlay priority
- Run grep -r priority /etc/portage/repos.conf/ to see priority values assigned to each repo
- Higher priority numbers mean the overlay takes precedence when the same package exists in multiple repos
- The main Gentoo repo typically has a lower priority so overlays can override packages when needed
grep -r priority /etc/portage/repos.conf/ 💡 Priority matters when two repos provide the same package. If an overlay has priority 50 and gentoo has priority -1000, the overlay version wins. This is how custom or patched packages override upstream.
○ Compare overlay vs main tree packages
- Run eix --in-overlay to list packages that come from overlays rather than the main tree
- If eix is not available, check installed packages with: qlist -Iv | while read pkg; do equery which $pkg 2>/dev/null; done | grep -v gentoo | head -20
- Packages from overlays may be newer versions, custom patches, or software not yet in the main tree
eix --in-overlay 2>/dev/null || echo "Try: eselect repository list to see enabled overlays" 💡 The Gentoo main tree is conservative — new software often lands in overlays first. The guru overlay is a popular community repository where new packages are submitted before potentially moving to the main tree.
Read and understand the Gentoo build recipes
○ Find an ebuild file
- Run ls /var/db/repos/gentoo/app-editors/vim/ to list the contents of the Vim package directory
- Identify the .ebuild files — each one represents a specific version available for installation
- Note the metadata.xml (package metadata and USE flag descriptions), Manifest (checksums), and files/ directory (patches)
ls /var/db/repos/gentoo/app-editors/vim/ 💡 Every Gentoo package lives in a category/name directory. The ebuild filename format is name-version.ebuild. The Manifest file contains cryptographic hashes to verify source tarballs.
Expected:
Ebuild files (.ebuild), metadata.xml, Manifest, and optionally a files/ directory with patches
○ Read an ebuild and identify build phases
- Pick the newest .ebuild file and read it: cat /var/db/repos/gentoo/app-editors/vim/vim-*.ebuild | head -80
- Look for phase functions: src_prepare() (apply patches), src_configure() (run ./configure), src_compile() (run make), src_install() (install files)
- Note the EAPI line at the top — this declares which version of the ebuild API the script uses
- Find the IUSE variable — it lists all USE flags this ebuild supports
cat /var/db/repos/gentoo/app-editors/vim/vim-*.ebuild | head -80 💡 Ebuilds are structured bash scripts. Portage calls each phase function in order. The EAPI version determines which helpers and features are available — EAPI 8 is current.
○ Understand dependency types
- In the ebuild, find the DEPEND, RDEPEND, and BDEPEND variables
- DEPEND = build-time dependencies (headers, libraries needed to compile)
- RDEPEND = runtime dependencies (libraries needed to run the installed software)
- BDEPEND = build host dependencies (tools like cmake or meson needed by the build system itself)
- Run equery depgraph app-editors/vim to visualize the dependency tree
equery depgraph app-editors/vim 💡 The three-way split (DEPEND/RDEPEND/BDEPEND) matters for cross-compilation. BDEPEND runs on the build host, DEPEND on the target, and RDEPEND at runtime. For normal installs, DEPEND and BDEPEND both run locally.
○ Explore the installed package database
- Run ls /var/db/pkg/ to see all categories with installed packages
- Drill into a category: ls /var/db/pkg/app-editors/ to see installed versions
- Each package directory contains metadata files: USE (active USE flags), CONTENTS (file manifest), CFLAGS (flags used to compile)
ls /var/db/pkg/ | head -30 💡 The /var/db/pkg/ database is how Portage tracks installed packages. It is a flat file database — no SQL, no binary formats. You can read everything with cat.
Expected:
Category directories mirroring the Portage tree structure, but only containing packages that are actually installed
○ Inspect a package build environment
- Find an installed package: ls /var/db/pkg/app-editors/
- Read its recorded USE flags: cat /var/db/pkg/app-editors/vim-*/USE
- Read its CFLAGS: cat /var/db/pkg/app-editors/vim-*/CFLAGS
- For the full build environment: bzcat /var/db/pkg/app-editors/vim-*/environment.bz2 | head -50
cat /var/db/pkg/app-editors/vim-*/USE 2>/dev/null && echo "---" && cat /var/db/pkg/app-editors/vim-*/CFLAGS 2>/dev/null 💡 The environment.bz2 file captures the complete bash environment at build time — every variable, function, and flag. This is how Portage detects when a rebuild is needed after config changes.
Explore the Linux kernel build system
○ View the running kernel configuration
- Run zcat /proc/config.gz | head -50 to decompress and view the first 50 lines of the running kernel config
- This file contains every CONFIG_* option used to build the currently running kernel
- Look for CONFIG_LOCALVERSION to see the custom version suffix, and CONFIG_SMP for multi-processor support
zcat /proc/config.gz | head -50 💡 The kernel config in /proc/config.gz is only available if CONFIG_IKCONFIG and CONFIG_IKCONFIG_PROC were enabled at build time. Gentoo kernels typically include these.
Expected:
Kernel config options starting with CONFIG_*, showing y (enabled), m (module), or lines commented out with # (disabled)
○ Check loaded kernel modules
- Run lsmod to see all currently loaded kernel modules
- The output shows module name, size in bytes, and how many other modules depend on it
- Look for filesystem modules (ext4, btrfs, xfs), network drivers, and GPU modules
lsmod 💡 Modules marked "m" in the kernel config can be loaded/unloaded at runtime. Built-in options ("y") are compiled directly into the kernel image and will not appear in lsmod.
○ Check kernel source version
- Run head -5 /usr/src/linux/Makefile to see the kernel version variables
- The first few lines define VERSION, PATCHLEVEL, SUBLEVEL, and EXTRAVERSION
- Together these form the full version string — compare with uname -r to verify they match
head -5 /usr/src/linux/Makefile 💡 The /usr/src/linux symlink points to the active kernel source tree. Gentoo manages this with eselect kernel. If the Makefile version differs from uname -r, a newer kernel source is staged but not yet built.
○ View kernel boot parameters
- Run cat /proc/cmdline to see the parameters passed to the kernel at boot
- Look for root= (root filesystem), init= (init system path), and any custom parameters
- Parameters like quiet and splash control boot verbosity; others configure hardware behavior
cat /proc/cmdline 💡 Boot parameters are set in the bootloader config (GRUB, systemd-boot, etc.). Some parameters can only be set at boot time — they configure the kernel before userspace starts.
○ Check kernel filesystem and feature support
- Run zcat /proc/config.gz | grep -i btrfs to check Btrfs filesystem support in the kernel
- CONFIG_BTRFS_FS=y means built-in; =m means available as a module; not present means disabled
- Try checking other features: grep -i ext4, grep -i kvm, grep -i cgroup to see virtualization and container support
zcat /proc/config.gz | grep -i btrfs 💡 Gentoo gives you full control over the kernel. Unlike binary distros that enable almost everything as modules, Gentoo users can build a minimal kernel with only the features they need — faster boot, smaller image, less attack surface.
What You Can Do
- Full Gentoo Linux QEMU VM with KDE Plasma desktop
- VNC desktop access (graphical) + terminal console
- Complete Portage tree with emerge, equery, eselect
- Inspect make.conf, USE flags, and package masks
- Browse the ebuild tree and package database
- Explore kernel configuration and modules
Learning Objectives
Beginner
- Navigate Portage and search packages
- Read make.conf configuration
- Use the VNC desktop
Intermediate
- Understand USE flags
- Explore binary package system
- Use equery for package analysis
Advanced
- Read and understand ebuilds
- Manage overlays and repositories
- Explore package masking
Expert
- Analyze ebuild phases
- Inspect kernel configuration
- Explore package database internals
Key Commands
emerge --searchSearch packagesemerge --infoSystem infoequery listList installedcat /etc/portage/make.confBuild config LIVE Connecting...
Waiting for VM desktop...
LIVE Connecting...
Session
--- Time Left --:--
CPU 0%
MEM 0%
About Argo OS
Argo OS is a custom Gentoo-based distribution optimized for distributed compilation. The build swarm uses 70+ cores across two sites to compile packages in parallel, with binary package distribution to all machines.
🔥66-core distributed build swarm
📦Binary package distribution via binhost
🌐Multi-site Tailscale mesh networking
⚡Custom CFLAGS and USE flag optimization