archforge
Modular post-installation toolkit for Arch Linux

🌐 English · Español

Module reference · Contributing · License

 

🪄 About

archforge automates the configuration of a freshly installed Arch Linux system. It runs independent modules that configure packages, services, security, networking, performance, input, console, graphics, and more. Every file archforge edits or creates is automatically backed up and can be reverted with archforge restore — including undoing files it created from scratch, not just restoring overwritten ones. Package installs and service/group state changes (systemctl enable, usermod, etc.) are applied directly and are not reverted by restore; the summary printed after each run lists the packages installed so you can remove them manually if needed.

Note

ArchWiki only (official): README text, module descriptions, links, and implementation guidance in this repository are based solely on the public ArchWiki — the official Arch Linux wiki. Where user repositories are involved, that means the same wiki (e.g. Arch User Repository, AUR helpers), not third-party blogs or unofficial guides. The wiki remains the authoritative, up-to-date source; archforge is a helper and may lag behind wiki edits.

 

🚀 Quick start

git clone https://github.com/h3n-x/archforge.git
cd archforge
chmod +x archforge
./archforge

Tip

Use ./archforge --dry-run first to see what would change without applying anything.

 

🖥️ Interactive menu

Note

Without --modules or --profile, a two-column numbered menu appears. Choose by number (1 3 5), by module id (pacman firewall), the word all for every module, or q to quit. Separate tokens with spaces or commas. Rows may show ⚠ when a module can touch hardware or deserves a quick review before applying.

 

🎯 System Profiles

Instead of choosing individual modules manually, apply a curated system configuration with --profile=NAME:

./archforge --profile=desktop-full

Profile	Target / Use Case	Base Software Modules
server	Headless servers, VPS or Home Labs	pacman, aur-helper, systemd, users-groups, network, dns, firewall, antivirus, locale, ssd, performance
desktop-minimal	Lightweight desktop / TWM base (Hyprland, Sway, i3)	pacman, aur-helper, systemd, users-groups, network, dns, firewall, keyboard, locale, fonts, libinput, audio, ssd, performance
desktop-full	Full daily workstation	desktop-minimal + bluetooth, printing
gaming	Dedicated gaming rigs	pacman, aur-helper, network, dns, firewall, keyboard, locale, fonts, libinput, audio, bluetooth, ssd, performance, steam

Note

Universal Security Baseline: Every profile includes dns (with DNSSEC / DoT) and firewall (nftables).

Automatic Hardware Resolution: By default, archforge scans the machine bus dynamically:

• Multi-GPU PCI Bus Scanning: Scans all PCI controllers (lspci), seamlessly configuring hybrid setups (e.g., integrated AMD APU + discrete NVIDIA GPU on laptops) without driver collision.
• Laptops: Inspects battery subsystems (/sys/class/power_supply) to add tlp and acpid on genuine mobile devices only.
• Sensors: Inspects virtualization via systemd-detect-virt, injecting sensors on bare-metal hardware and skipping inside VMs.

Use --no-hardware-detect if you want strictly the curated software base without auto-detecting hardware modules.

 

📦 Install (system-wide)

sudo make install

This installs the archforge script and copies lib/ and modules/ under $(PREFIX)/share/archforge (default prefix: /usr/local). See the Makefile for DESTDIR and PREFIX.

 

🎨 Preview

_{Interactive TUI: run ./archforge in a UTF-8 terminal for the live experience.}

 

📋 Available modules

ID	Name	Category	Description
acpid	Power: ACPI events (acpid)	Power Management	Lid close suspend, power button events
amd	Graphics: AMD GPU (AMDGPU)	Graphics	Mesa, RADV Vulkan, early KMS, optional 32-bit multilib
antivirus	Security: Antivirus (ClamAV)	Security	ClamAV with clamd config, freshclam, optional on-access scanning + scan timer
audio	Peripherals: Audio (PipeWire & WirePlumber)	Peripherals	PipeWire, WirePlumber, PulseAudio emulation
aur-helper	Package Management: AUR helper	Package Management	Detect/install AUR helper (yay/paru), makepkg optimization
bluetooth	Peripherals: Bluetooth (BlueZ)	Peripherals	BlueZ, bluetoothctl, blueman GUI
dns	Security: DNS configuration	Security	DNS provider detection, 6 providers, DNSSEC, DoT
firewall	Security: Firewall (nftables)	Security	nftables profiles (desktop/server/strict), SSH rate limiting, drop logging
fonts	Console: Fonts	Console	terminus-font, noto-fonts, ttf-liberation, vconsole.conf
intel	Graphics: Intel Graphics	Graphics	Mesa, ANV Vulkan, VA-API acceleration, optional 32-bit multilib
keyboard	Input: Keyboard layout	Input	Console keymap, X11 layout via localectl
libinput	Input: libinput (touchpad/mouse)	Input	Touchpad, natural scroll, TrackPoint, Wayland note
locale	Console: Locale & timezone	Console	locale-gen, timezone, hardware clock sync, NTP
network	Networking: network configuration	Networking	Hostname, /etc/hosts, NetworkManager, WiFi powersave, regulatory domain, MAC randomization
nouveau	Graphics: Nouveau (open-source NVIDIA)	Graphics	Open-source NVIDIA driver
nvidia	Graphics: NVIDIA driver	Graphics	Proprietary NVIDIA driver install
pacman	Package Management: pacman	Package Management	Configure pacman.conf, multilib, reflector, keyring, pkgfile, paccache
performance	Optimization: Performance	Optimization	Network sysctls, THP, zram, OOM killer, CPU governor
printing	Peripherals: Printing (CUPS)	Peripherals	CUPS, printer drivers, avahi
sensors	Optimization: Hardware sensors	Optimization	lm_sensors, sensor detection
ssd	Optimization: SSD	Optimization	TRIM verify, fstrim timer, continuous discard, noatime, tmpfs /tmp
steam	Gaming: Steam	Gaming	Steam, Proton/Wine deps, fd-limit, GameMode, MangoHud
systemd	System Services: systemd	System Services	Persistent journal drop-in, boot analysis, timesyncd
tlp	Power: TLP	Power Management	Battery optimization, charge thresholds, USB denylist
users-groups	System: Users and Groups	System Services	User accounts, groups, sudo config
vmware-host	Virtualization: VMware Workstation (host)	Virtualization	VMware Workstation host setup

 

⚙️ CLI flags

--modules m1,m2,...    Run specific modules (skips menu)
--dry-run              Show what would change, execute nothing
--yes, -y              Skip all confirmation prompts
--aur-helper=NAME      Override AUR helper (yay, paru, ...)
--help, -h             Show help
--version              Show version

 

🔄 Restore

./archforge restore

Shows previous sessions and lets you selectively restore backed-up files.

 

🛠️ Development

make lint    # shellcheck
make test    # bats
make check   # lint + test

 

📎 Requirements

• Arch Linux (or compatible derivative)
• bash >= 5.0
• sudo privileges

 

📚 Documentation

Resource	Description
docs/en/modules.md	Module list with packages and wiki links (English)
docs/es/modules.md	Same, Spanish
README.es.md	This readme in Spanish

 

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for tests, shellcheck, and the module API (module_info / module_run).

 

🙋 FAQ

• Q: How do I skip the menu?
  A: Pass explicit module ids: ./archforge --modules pacman,firewall (comma-separated), or use a preset profile: ./archforge --profile=desktop-full. To run everything without typing each id, use the interactive menu and enter all.

• Q: Can I combine a profile with additional modules?
  A: Yes. Pass --profile=NAME --modules mod1,mod2. The modules are merged and automatically sorted into canonical execution order without duplicates.

• Q: Where are backups stored?
  A: By default under ~/.local/share/archforge/backups/<session-id>/. Override with the BACKUP_BASE_DIR environment variable. Use ./archforge restore to pick a previous session interactively.

 

💝 Thanks

• Arch Linux and the ArchWiki authors
• README layout inspired by the Catppuccin community’s port templates (badges, spacing, sections). Not affiliated — only structural inspiration.

 

Copyright © 2026 h3n-x