Introduction
This is the HxS Handbook for the 26a3 release of the HxS Operating System, documentings its functionality, configuration, and usage.
License
Copyright (c) 2026 juanvel400.
Licensed under CC-BY-4.0.
Code snippets authored for this handbook are also available under 0BSD.
Installation Guide for HxS 26a3
This guide details how to install HxS 26a3 on an x86_64 UEFI machine.
The Live Installer Image is based on HxS 26a3 GNU, extended with the efi subset.
1. Configure the Live System
1.1 Network Configuration
Programs & Packages:
dhcpcd(8)fromdhcpcdip(8)fromiproute2ping(1)frominetutils
The HxS Live System assumes an active internet connection; currently Wi-Fi is not supported.
Tip
If your network uses it, execute the DHCP client with
dhcpcd(8):dhcpcd eth0 # look up the appropriate network device with `ip link`
The /etc/resolv.conf file lists DNS servers used to resolve domain names. The following command sets 1.1.1.1 as the default nameserver, with 8.8.8.8 as a fallback:
echo "nameserver 1.1.1.1" >/etc/resolv.conf
echo "nameserver 8.8.8.8" >>/etc/resolv.conf
Finally, use ping(1) to test the network connection.
ping -c 3 main.hxs.juanvel400.com
1.2 XPT
Programs & Packages:
xpt(8)fromxpt
The Live System does not provide any xpt(8) repositories in /etc/xpt.d/index. Write the 26a3 main repository (https://main.hxs.juanvel400.com/archive/26a3/x86_64) to it:
echo "https://main.hxs.juanvel400.com/archive/26a3/x86_64" >/etc/xpt.d/index
Synchronize the xpt(8) package database:
xpt -s
2. Partitioning
Programs & Packages:
lsblk(8),mount(8)andcfdisk(8)fromutil-linuxmkfs.ext4(8)frome2fsprogsmkfs.fat(8)fromdosfstoolsmkfhs(1)fromxpt
Use lsblk(8) to list block devices (disks and partitions):
lsblk
The guide assumes
/dev/sdaas the target disk
Use cfdisk(8) to create a partition scheme for the system.
Tip
The following example serves as a reference partition scheme for most HxS systems
Partition Size Type Filesystem Mountpoint /dev/sda1512MiBto1GiBEFI System PartitionFAT32/boot/efi/dev/sda2At least 1GiB, preferably more than10GiBLinux root (x86_64)ext4//dev/sda3Usually 2GiBLinux swapswap<none>UEFI systems usually use
GPT(GUID Partition Table). Ensure the disk’s partition table is set toGPT
Warning
Utilities such as
mkfs.ext4(8)ormkfs.fat(8)wipe entire partitions. Make sure the partition is safe to erase.
Format the root partition using mkfs.ext4(8):
mkfs.ext4 /dev/sda2
Note
On a fresh disk, format the
ESP. If the disk has other Operating Systems, skip this.To format the
ESP, usemkfs.fat(8):mkfs.fat -F 32 /dev/sda1
Mount root on /mnt using mount(8):
mount /dev/sda2 /mnt
Create the base system structure using mkfhs(1):
mkfhs /mnt
Then, mount the ESP using mount(8):
mount --mkdir /dev/sda1 /mnt/boot/efi
2.1 The Swap Partition
Programs & Packages:
fallocate(1),mkswap(8)andswapon(8)fromutil-linuxchmod(1)from thesystem:coreutilsprovider (sbase,coreutils,pxbase)
Most systems may benefit from a swap partition, used to extend physical RAM by moving inactive memory pages to it.
To format a partition as swap using mkswap(8):
mkswap /dev/sda3
Alternatively, a file can be created and used as a swap partition without repartitioning the disk.
Allocate 2GiB to /usr/swap0 with fallocate(1), set the permissions to rw------- with chmod(1) and format it as swap with mkswap(8):
fallocate -l 2GiB /mnt/usr/swap0
chmod 600 /mnt/usr/swap0
mkswap /mnt/usr/swap0
To enable swap using swapon(8):
swapon /dev/sda3 # or /mnt/usr/swap0
3. Bootstrapping HxS
3.1 Choosing a set
HxS provides several sets, predefined collections of packages that compose a base system, each suited to different use cases.
3.1.1 The Standard Set (standard)
This set provides first-class HxS packages, including pxbase, a core user utilities implementation, and adam, a sysvinit-compatible init system.
This set is experimental, as the projects it depends on are still experimental and prone to breaking.
3.1.2 The GNU Set (gnu)
This set is built on battle-tested GNU packages, including coreutils, the GNU file, text, and shell utilities, and bash, the GNU Bourne-Again Shell.
This set is preferred for setups that require stability, compatibility, or prefer a complete, assembled system.
3.1.3 The Suckless Set (suckless)
This set uses packages from the suckless Project, which strives for quality and minimalism. The packages include: sbase, a collection of portable unix tools, sinit, a suckless init, and ubase, a collection of unportable tools (alternative to util-linux).
HxS does not provide
/etc/rc.init,/etc/rc.poweroff, or/etc/rc.reboot. The user is expected to provide those.
3.1.4 The Minimal Set (minimal)
The Minimal Set is a trimmed-down version of Standard, using statically-linked builds of pxbase, adam, and xpt, and featuring a reduced base package set.
This set is designed for minimal containers, embedded systems, or rescue environments where size is a major priority.
3.1.5 The Suckless-Minimal Set (suckless-minimal)
This set is a trimmed-down version of the Suckless Set. Similarly to the Minimal Set, the Suckless-Minimal set uses statically-linked builds of sbase, ubase, sinit, and xpt.
3.2 Subsets
Unlike sets, subsets are designed to expand a base installation by providing packages that complement a specific feature or necessity.
3.2.1 efi
The efi subset includes packages to boot or administer UEFI-based systems.
Packages included by this subset are: popt, efivar, efibootmgr, and grub-efi.
3.3 Using hxsbootstrap(1) to Bootstrap a Base System
Programs & Packages:
hxsbootstrap(1)fromhxsbootstrap
Use hxsbootstrap(1) to bootstrap a base system:
hxsbootstrap \
-x \
-d /mnt \
-s standard \
-S efi \
-v 26a3
Flags
-x: Use the systemxpt(8)instead of bootstrappingxpt.static-d /mnt: Bootstrap HxS on/mnt-s standard: Use thestandardset-S efi: Install theefisubset-v 26a3: Bootstrap HxS 26a3
4. Configuring the Base System
4.1 Entering the Base System
Programs & Packages:
ecw(8)fromxptcp(1),chroot(1)from thesystem:coreutilsprovider (coreutils,sbase,pxbase)
First, copy the /etc/resolv.conf file from the live system using cp(1):
cp /etc/resolv.conf /mnt/etc/resolv.conf
After bootstrapping, all the system configuration must be made inside a chroot.
The ecw(8) program provides a wrapper around chroot(1):
ecw /mnt
4.2 Configuring the Shell
Programs & Packages:
bash(1)frombashdash(1)fromdashchsh(1)fromutil-linuxln(1)from thesystem:coreutilsprovider (coreutils,sbase,pxbase)
Note
All sets use the
dash(1)shell, except for thegnuset, which usesbash(1)
For compatibility with most scripts, symlink the installed shell to /bin/sh using ln(1):
ln -sf dash /bin/sh # or `ln -sf bash /bin/sh` for the gnu set
Set the root user’s shell using chsh(1):
chsh -s /bin/dash root # or /bin/bash
4.3 The Package Manager
Programs & Packages
xpt(8)fromxpt
Important
Minimal sets ship with a static version of the
xptpackage, this is a trimmed-down version ofxptthat lacks the networking subsystem entirely. Minimal sets can skip this section.The complete version of
xptdepends on:libarchive,openssl,zstd,pkgconf,zlib,xz,bzip2, andmusl.To install
xptin almost any HxS system, write the main repository to/etc/xpt.d/index, then exit the chroot, as outlined in 6. Reboot. Then, use the following commands to refresh the Package Database, uninstallxpt.static, and installxpt:xpt -d /mnt -s xpt -d /mnt -rp xpt.static xpt -d /mnt -in xptThen, return to the chroot using
ecw(8)as outlined in 4.1 Entering the Base System
The newly installed system does not provide any repositories, nor does it have a configured xpt(8).
Similarly to 1.2 XPT, write the 26a3 main repository in /etc/xpt.d/index:
echo "https://main.hxs.juanvel400.com/archive/26a3/x86_64" >/etc/xpt.d/index
Synchronize the xpt(8) Package Database:
xpt -s
4.4 Users
Programs & Packages
passwd(8)anduseradd(8)fromshadow
First, set the root user password using passwd(8):
passwd root
Using the root user by default is insecure. Create a regular user for most use cases using useradd(8):
useradd -m johndoe
Assign it a password using passwd(8):
passwd johndoe
4.5 The /etc/inittab File
Programs & Packages:
adam(8)fromadamcp(1)from thesystem:coreutilsprovider (coreutils,sbase,pxbase)vim(1)fromvimnano(1)fromnano
Important
The
sucklessandsuckless-minimalsets do not use/etc/inittab. Instead, they use the/etc/rc.init,/etc/rc.poweroff, and/etc/rc.rebootscripts.Use the Morpheus Init Scripts as a reference for writing your own.
The adam(8) init system uses a file called inittab to initialize processes that the system requires to function normally.
Copy /usr/share/adam/examples/inittab to /etc/inittab using cp(1):
cp /usr/share/adam/examples/inittab /etc/inittab
Use the editor provided by the system to modify /etc/inittab:
vim /etc/inittab
Note
The
gnuset providesnano(1)instead ofvim(1), whereas thesuckless,minimal, andsuckless-minimalsets do not provide an editor at all.
Tip
On HxS systems where
xpt(8)supports networking, installvim(1)using:xpt -in vim
4.6 System Networking
Programs & Packages
adam(8)fromadamdhcpcd(8)fromdhcpcd
To identify the system in the network, adam(8) reads the /etc/hostname file and sets its contents as the system’s hostname.
Set the system’s hostname in /etc/hostname using:
echo "hxs" >/etc/hostname
Tip
To execute the DHCP client (
dhcpcd(8)) on boot, append the following line toinittabdhcp:2345:respawn:/sbin/dhcpcd -B
4.7 The Filesystem Table
Programs & Packages:
blkid(8)fromutil-linux
The /etc/fstab file is used to specify which filesystems to mount at boot time.
Each partition is assigned a UUID. To look up all partitions and their UUIDs, use blkid(8):
blkid
Example /etc/fstab file:
# view fstab(5) from util-linux for further information on the /etc/fstab file
# fs mp fstype mntops dump pass
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx / ext4 rw,relatime 0 2
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx /boot/efi vfat rw,relatime,utf8 0 2
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx none swap sw 0 0
# /usr/swap0 none swap sw 0 0
5. Making the System Bootable
5.1 Installing a Kernel
Important
There is no Kernel Package available in any of the main repositories, thus the user is expected to provide their own kernel and configure it.
This section is considered TODO
5.2 Installing a Bootloader
Programs & Packages:
grub-mkconfig(8),grub-install(8)fromgrub-efi
So far, the system is not bootable. The grub-efi package provides the GNU Grand Unified Bootloader. Install it to the EFI System Partition using grub-install(8):
grub-install \
--target=x86_64-efi \
--bootloader-id=HxS \
--efi-directory=/boot/efi
If you attempt to boot to GRUB, you will find a bare grub> prompt. This is because there are no boot entries configured. Use grub-mkconfig(8) to generate a /boot/grub/grub.cfg file:
grub-mkconfig -o /boot/grub/grub.cfg
6. Reboot
Programs & Packages:
ecw(8)fromxptreboot(8)fromadamumount(8)fromutil-linux
Exit ecw(8) by closing the interactive shell:
# exit
exit
Alternatively, use the
Ctrl-Dshortcut to send anEOFsignal to the shell, thus closing it.
If swap was configured and enabled in 2.1 The Swap Partition, disable it using swapoff(8):
swapoff /dev/sda3 # or /mnt/usr/swap0
Unmount the filesystem recursively using umount(8):
umount -R /mnt
Use reboot(8) from adam to restart the system:
reboot
The first boot is expected to show something similar to the following:
HxS 26a3 (x86_64)
hxs login:
Type the username, and then the password, of the user created in 4.4 Users. Alternatively, log in as root.
The HxS PackageTracker
Programs & Packages:
ebs(5)andebs(1)fromxpt
The HxS PackageTracker is a growing tree of over 120 ebs(5) formula, describing how to build packages using the ebs(1) build system.
PackageTracker is inspired by void-packages, the FreeBSD ports tree, and, loosely, the Arch User Repository,
Important
Most formulae assume the presence of a native compilation toolchain, which is not included in the binary repositories, the user is expected to bootstrap their own, using the
x86_64-hxs-linux-musltriple.
1. Getting the PackageTracker Tree
Programs & Packages:
git(1)fromgit
Note
Most HxS systems are expected to have a copy of PackageTracker available in
/usr/tracker
As root, use git(1) to clone the PackageTracker tree into /usr/tracker:
git clone https://github.com/juanvel4000/HxS-PackageTracker.git /usr/tracker
2. Working with PackageTracker
2.1 Search for a Formula
Programs & Packages:
find(1)fromfindutilsgrep(1)fromgrep
Use find(1) and grep(1) to look up formulae in the tree:
find /usr/tracker -type f -name "*.ebs" | grep -F -e "<name>"
Tip
The following shell script creates a wrapper around the command above, under a command named
qtracker:cat << 'EOF' > /usr/local/bin/qtracker #!/bin/sh set -eu if test "$#" -ne 1; then echo "usage: qtracker query" exit 1 fi results=$(find /usr/tracker -type f -name "*.ebs" | grep -F -e "$1" || :) if test -z "$results"; then echo "! nothing found" exit 1 fi printf '%s\n' "$results" EOF chmod 755 /usr/local/bin/qtracker
2.2 Building a formula
Programs & Packages:
ebs(1)fromxpt
Tip
Prefer not to build packages as the
rootuser
Use the ebs(1) build system to build a formula:
ebs build /usr/tracker/hello/hello-0.1.3.ebs
If a second argument is not provided, ebs(1) produces an .xpt package under the filename <name>-<version>.xpt.
Install the built package using xpt(8):
xpt -if hello-0.1.3.xpt
3. Writing ebs(5) formulae
Programs & Packages:
ebs(5)fromxpt
View the ebs(5) manual page and use /usr/share/xpt/examples/ebs.formula as a reference for building ebs(5) formula.