A meta-wrapper package manager — unify Pacman, Nix, and Flatpak under a single CLI.
curl -fsSL https://raw.githubusercontent.com/ElioNeto/agnostikos/main/scripts/install.sh | shThe script automatically detects your architecture (amd64 / arm64), fetches the latest release from GitHub, verifies the SHA256 checksum, and installs the agnostic binary to /usr/local/bin (or ~/.local/bin as fallback).
Download the pre-built binary for your platform from the Releases page, extract it, and place it in your PATH:
tar -xzf agnostikos_*.tar.gz
sudo install agnostic /usr/local/bin/AgnosticOS is a meta-wrapper package manager that abstracts multiple package ecosystems behind a single, unified command-line interface. Instead of learning pacman -S, nix profile install, and flatpak install separately, you use agnostic install — the tool dispatches to the right backend automatically.
Built from scratch in Go, AgnosticOS is designed for developers who work across distributions and want a consistent, scriptable package management experience.
Key features:
- 🔀 Multi-backend dispatch — Pacman, Nix, and Flatpak, all from one CLI
- 📋 Config-driven installs — declare your packages in
agnostic.yaml - 🔍 Full lifecycle management —
agnostic search,list,install,remove,updatefor complete package management - 🖥️ Terminal UI — interactive package browser with
agnostic tui - 🌐 Web UI — browser-based management with
agnostic serve - 🔒 Namespace isolation — optional Linux mount namespace sandboxing
- 🏗️ Build pipeline — full ISO generation: RootFS → toolchain → kernel → busybox → initramfs → GRUB → ISO (BIOS or UEFI)
- 💿 ISO builder — standalone ISO generation from an existing RootFS (
agnostic iso)
| Backend | Scope | Use case | Status |
|---|---|---|---|
| Pacman | Arch Linux | Native Arch packages | ✅ |
| Nix | NixOS / multi | Reproducible, declarative pkgs | ✅ |
| Flatpak | Universal | Sandboxed desktop apps | ✅ |
# Clone
git clone https://github.com/ElioNeto/agnostikos.git
cd agnostikos
# Install dependencies & build
make deps
make build
# See available commands
./build/agnostic --helpInstall a single package:
./build/agnostic install firefox --backend flatpakInstall from config file:
./build/agnostic install --config agnostic.yamlList installed packages:
./build/agnostic listSearch for packages:
./build/agnostic search neovim --backend nixRemove a package:
./build/agnostic remove firefoxUpdate packages:
./build/agnostic update # update all packages
./build/agnostic update firefox # update a specific package
./build/agnostic update --dry-run # simulate update without executingLaunch the TUI:
./build/agnostic tuiStart the Web UI server:
./build/agnostic serveThe build command runs the complete ISO generation pipeline — from creating the RootFS
to producing a bootable ISO image.
# Default build (auto-detects architecture, uses kernel 6.6, busybox 1.36.1)
sudo ./build/agnostic build --output /tmp/agnostikos.iso
# Build from a recipe file
./build/agnostic build recipes/base.yaml
# Quick build (skip lengthy toolchain compilation)
./build/agnostic build --skip-toolchain --output /tmp/agnostikos.iso
# Full build with UEFI
sudo ./build/agnostic build \
--uefi \
--output /tmp/agnostikos.isoNote: The
bootstrapsubcommand is still available internally for advanced use (agnostic bootstrap --help), butbuildis the recommended entry point.
| Flag | Default | Description |
|---|---|---|
-o, --output |
agnostikos-latest.iso |
Output ISO path |
-t, --target |
$AGNOSTICOS_ROOT |
RootFS target directory |
--device |
— | Disk for BIOS grub-install |
--efi-partition |
— | ESP partition for UEFI grub-install |
--uefi |
false |
Enable UEFI boot support |
--kernel-version |
6.6 |
Linux kernel version |
--busybox-version |
1.36.1 |
Busybox version |
--arch |
auto-detect | Target architecture (amd64, arm64) |
--recipe |
— | Load settings from a YAML recipe file |
--skip-toolchain |
false |
Skip toolchain compilation |
--skip-kernel |
false |
Skip kernel compilation |
--skip-busybox |
false |
Skip busybox compilation |
--skip-initramfs |
false |
Skip initramfs generation |
--skip-grub |
false |
Skip GRUB installation |
--force |
false |
Rebuild all steps from scratch |
agnostikos/
├── cmd/agnostic/ # CLI entry point (Cobra)
├── internal/
│ ├── bootstrap/ # RootFS, kernel, busybox, initramfs, GRUB
│ ├── config/ # YAML config parsing
│ ├── dotfiles/ # Dotfile backup/restore/sync
│ ├── iso/ # ISO builder (xorriso/mkisofs)
│ ├── isolation/ # Linux namespace isolation
│ ├── manager/ # PackageService interface + backends
│ ├── server/ # Web UI server
│ └── tui/ # Terminal UI (Bubble Tea)
├── recipes/ # YAML image definitions (base.yaml)
├── scripts/ # QEMU runner, CI helpers
├── docs/ # Architecture & requirements docs
├── agnostic.yaml.example # Example configuration
├── Makefile # Build, test, lint, ISO targets
└── main.go # Binary entry point
| Tool | Version / Notes |
|---|---|
| Go | 1.22+ |
| GNU Make | Any recent version |
| grub-install | GRUB 2 (apt install grub-efi-amd64 or grub-pc) |
| xorriso | ISO creation (apt install xorriso) |
| qemu-system-x86 | QEMU for ISO testing (apt install qemu-system-x86) |
| ovmf | UEFI firmware for QEMU (apt install ovmf) |
| git | Version control |
See docs/requirements.md for detailed setup instructions.
make build # Compile CLI binary
make test # Run unit tests with race detector
make test-iso # Test ISO in QEMU (graphical)
make test-iso-headless # Test ISO in QEMU (headless, for CI)
make lint # Run golangci-lint
make fmt # Format Go code
make install # Install to /usr/local/bin
make clean # Remove build artifacts
make iso # Build ISO from RootFS
make bootstrap # (internal) RootFS bootstrap pipeline (requires root)
make dev # Run in development modeNote:
make buildruns the full pipeline and does NOT require root unless you use--device/--efi-partitionfor GRUB installation into real hardware.make bootstrapis kept for backward compatibility butmake build [ARGS="..."]is the recommended target.
version: "1.0"
locale: pt_BR.UTF-8
timezone: America/Sao_Paulo
packages:
base:
- vim
- git
- curl
extra:
- docker
- neovim
backends:
default: pacman
fallback: nix
user:
name: dev
shell: /bin/zshThen run:
agnostic install --config agnostic.yaml- CLI bootstrap with Cobra
- PackageService interface
- Pacman backend
- Nix backend
- Flatpak backend
- Namespace isolation (CLONE_NEWNS)
- ISO builder (BIOS + UEFI)
- CI pipeline (build, test, lint)
- RootFS generator (FHS + usrmerge)
- Toolchain download (binutils, gcc, glibc)
- GRUB installation (BIOS + UEFI, auto ESP mount)
- Kernel compilation
- Busybox compilation
- Initramfs generation
- Full LFS bootstrap recipe
- QEMU smoke test in CI
-
agnostic.yamlschema validation - Multi-architecture support (ARM64)
After booting a custom AgnosticOS ISO, the system starts with busybox init as the PID 1 process.
The kernel launches /init which is a symlink to busybox's /sbin/init. The init process reads /etc/inittab to determine what to run:
::sysinit:/etc/init.d/rcS → system initialization
::ctrlaltdel:/sbin/reboot → Ctrl+Alt+Del handling
::shutdown:/sbin/swapoff -a → swap teardown
::shutdown:/bin/umount -a -r → filesystem unmount
The boot script /etc/init.d/rcS mounts virtual filesystems, sets up device nodes via mdev, and configures the hostname.
- Auto-login mode (default for live sessions): If
AutoLoginUseris set in the bootstrap config, the configured user is automatically logged in ontty1via/bin/login -f <user>. - Manual login mode: When no auto-login user is configured,
initpresents a login prompt on the console (::askfirst:-/bin/sh). The default credentials depend on the contents of/etc/passwdand/etc/shadowin the rootfs.
Once logged in, the following agnostic commands are available:
| Command | Description |
|---|---|
agnostic tui |
Launch the interactive terminal UI (TUI) |
agnostic install <package> |
Install a package via the default backend |
agnostic install --config <file> |
Install packages declared in a YAML config |
agnostic list |
List installed packages across all backends |
agnostic search <query> |
Search for packages in configured backends |
agnostic remove <package> |
Remove an installed package |
agnostic backend list |
Show available backends (pacman, nix, flatpak) |
# Install a single package using the default backend
agnostic install firefox
# Install using a specific backend
agnostic install firefox --backend flatpak
# Install from a declarative config file
agnostic install --config /etc/agnostic.yaml# Full pipeline: RootFS → toolchain → kernel → busybox → initramfs → GRUB → ISO
sudo make build ARGS="--output /tmp/custom.iso"
# Quick build (skip toolchain, use cached artifacts)
sudo make build ARGS="--skip-toolchain --output /tmp/custom.iso"
# Build with a recipe file
./build/agnostic build recipes/base.yamlPre-built binaries for Linux (amd64 and arm64) are available on the Releases page.
Each release includes:
agnostikos_<version>_linux_amd64.tar.gzagnostikos_<version>_linux_arm64.tar.gzchecksums.txt(SHA256)
Man pages are included in the release archive under docs/man/. To install them:
sudo install -d /usr/local/share/man/man1
sudo install -m 644 docs/man/* /usr/local/share/man/man1/
sudo mandb # update the man databaseYou can also generate the latest man pages from source:
make docs
sudo install -m 644 docs/man/* /usr/local/share/man/man1/
sudo mandbPlease read CONTRIBUTING.md for details on our code of conduct, development setup, and the PR process.
MIT — see LICENSE
Author: Elio Neto — Santa Catarina, Brasil