☰ navigation

Astral Package Manager

Astral is a monolithic, source-based package manager written entirely in POSIX sh. It handles package installation, removal, dependency resolution, service management, security verification, and transaction rollback all from a single script.

Installation

Prerequisites

• POSIX-compliant shell (bash, dash, etc.)
• curl or wget
• sha256sum, tar, make, gcc
• Root access

Install

curl -O https://raw.githubusercontent.com/Astaraxia-Linux/Astral/main/astral
chmod +x astral
sudo mv astral /usr/bin/

Configuration

Create /etc/astral/astral.stars (the main config file):

# Build flags
CFLAGS="-O2 -pipe -march=native"
CXXFLAGS="$CFLAGS"
MAKEFLAGS="-j$(nproc)"

# Repositories
AOHARU_URL="https://izumi-sonoka.github.io/AOHARU/"
ASURA_URL="https://codeberg.org/Izumi/ASURA/raw/branch/main"

# Safety
SAFETY_SIGNATURE_VERIFY=1
SAFETY_SECURE_DOWNLOAD=1
CCACHE_ENABLED="yes"

Basic Usage

Command	Description
astral -S <pkg>	Install package from AOHARU
astral -SA <pkg>	Install package from ASURA overlay
astral -S <p1> <p2>	Install multiple packages in parallel
astral -R <pkg>	Remove package
astral -r <pkg>	Remove package and orphaned deps
astral -R <p1> <p2>	Remove multiple packages in parallel
astral -U	Update all installed packages
astral -Ss <query>	Search AOHARU and ASURA
astral -Si <pkg>	Show package info
astral -Sl	List all available packages
astral -ll <pkg>	List installed files
astral --count	Show package statistics
astral --graph-deps <pkg>	Show dependency graph
astral --preview <pkg>	Preview what would be installed
astral --use <flag> -S <pkg>	Install with specific USE flag

Package Management

World Set

The world set tracks explicitly installed packages (not pulled in as deps).

Command	Description
astral --world-show	List world set packages
astral --world-add <pkg>	Add to world set
astral --world-remove <pkg>	Remove from world set
astral --world-sets	Show named package sets
astral --world-depclean	Remove unneeded deps not in world
astral --calc-system	Calculate system package set

Package Holds

Command	Description
astral --hold <pkg>	Prevent package from being updated
astral --unhold <pkg>	Remove hold
astral --list-held	Show all held packages

Verification

Command	Description
astral --verify-integrity <pkg>	Verify installed files against checksums
astral --verify-reproducible <pkg>	Verify reproducible build
astral --validate <pkg>	Validate recipe syntax
astral --check-version <pkg>	Check for upstream version updates

Recipe Formats

Astral supports three recipe formats. v3 is the current standard. All formats are backwards compatible.

v3 Format

$PKG.Version = "3"

$PKG.Metadata: {
    Version = "1.2.3"
    Description = "A short description"
    Homepage = "https://example.com"
    Category = "app-misc"
};

$PKG.Depend.BDepends: {
    gcc
    make
    cmake
};

$PKG.Depend.RDepends: {
    glibc
    zlib
};

$PKG.Depend.Optional: {
    python3
};

$PKG.Sources: {
    urls = "https://example.com/pkg-1.2.3.tar.xz"
};

$PKG.Checksums: {
    sha256:abc123... pkg-1.2.3.tar.xz
};

$PKG.Build: {
    cd pkg-1.2.3
    ./configure --prefix=/usr
    make -j$(nproc)
};

$PKG.Package: {
    cd pkg-1.2.3
    make DESTDIR="$PKGDIR" install
};

$PKG.PostInstall: {
    systemctl enable myservice 2>/dev/null || true
};

$PKG.PostRemove: {
    systemctl disable myservice 2>/dev/null || true
};

Git Sources

$PKG.Sources: {
    urls = "git+https://github.com/user/repo#branch=main"
};

$PKG.Checksums: {
# git sources don't use checksums
};

Dependency Types

Section	Description
BDepends	Build-time only dependencies
RDepends	Runtime dependencies
PDepends	Post-install dependencies
IDepends	Install-time dependencies
Optional	Optional runtime dependencies

Service Management

Astral detects your init system automatically (systemd, OpenRC, runit, s6, SysVinit) and wraps all service commands.

Command	Description
astral start <svc>	Start a service
astral stop <svc>	Stop a service
astral restart <svc>	Restart a service
astral enable <svc>	Enable service at boot
astral disable <svc>	Disable service at boot
astral status <svc>	Show service status

Security

GPG Signing

# Sign a package
astral --sign <pkg> --key YOUR_KEY_ID

# Verify a package signature
astral --verify <pkg>

# Add a key to the Web of Trust
astral --trust-key KEY_ID

Safety Toggles

Controlled via /etc/astral/astral.stars:

Flag	Default	Description
SAFETY_SIGNATURE_VERIFY	1	Verify GPG signatures on packages
SAFETY_SECURE_DOWNLOAD	1	Reject unverified index files
SAFETY_CHECKSUM_STRICT	1	Fail on checksum mismatch

Transactions & Rollback

Every install/remove operation is recorded as a transaction. You can roll back to any previous state.

# List recent transactions
astral --transactions

# Roll back the last operation
astral --rollback

# Recover from an interrupted build
astral --recover

# Check what's locked (interrupted builds)
astral --lock-info

Advanced Features

Sandbox Isolation

Astral supports multiple sandbox backends for isolated builds:

Backend	Description
bubblewrap	Rootless container isolation (recommended)
chroot	Classic chroot isolation
fakechroot	Userspace chroot (no root required)
fakeroot	Fake root for packaging only

# Test sandbox
astral --sandbox-test

# Build in chroot
astral --chroot /mnt/lfs

Environment & Debugging

# Show current build environment
astral --show-env

# Verbose output
astral -v -S <pkg>

# JSON output for scripting
astral -ll <pkg> --json

# Parallel build flag
astral --parallel-build -S <pkg>

# Clean temp build files
astral --cleanup-temp

Chroot & Horizon Integration

# Enter chroot
astral --chroot /mnt/lfs

# Horizon commands
astral -h --init
astral -h --stage 1
astral -h --stage 2
astral -h --stage 3
astral -h --status

Troubleshooting

Problem	Fix
Another instance is running	sudo rm -rf /var/lock/astral.lock.d
Checksum mismatch	Upstream changed the file. Re-download and update the recipe checksum.
Interrupted build	astral --lock-info to see state, astral --recover to resume
Service not detected	Check which systemctl rc-service sv s6-rc Astral uses the first one found
Index signature failed	Set SAFETY_SECURE_DOWNLOAD=0 temporarily, or re-import the repo GPG key
Build fails with dep errors	Run astral --graph-deps <pkg> to trace the dep chain