Astral Package Manager Documentation

"Because compiling from source should be less painful than a root canal"

Version: 5.3.0.0 Main
Last Updated: 06 March 2026 (GMT+8)
Maintained by: One Maniac (yes, just one)

Made in Malaysia, btw

Introduction

What is Astral?

Astral is a minimal POSIX package manager for Astaraxia Linux. It builds packages from source because apparently, we hate ourselves enough to avoid binary packages. Think of it as Gentoo's Portage, but written by someone who values their sanity (debatable).

Why Astral?

Source-based: Because you totally want to compile everything
POSIX-compliant: Works on any UNIX-like system (in theory)
Minimal dependencies: Just sh, curl, and your tears
Four recipe formats: dir, v1, v2, and v3 (because backwards compatibility is a thing)
Smart dependency resolution: It won't delete your /usr (anymore 😭)
Parallel builds and removals: Because waiting is for the weak
Atomic transactions with rollback: Because mistakes happen
Built-in service management: init-system-agnostic, works everywhere
Security features: GPG signing, certificate pinning, FIM, audit trails

Why Not Astral?

You value your time
You have a slow computer
You prefer binary packages
You're a normal person

Installation

Prerequisites

You'll need:

A POSIX-compliant shell (bash, dash, etc.)
curl and/or wget (for downloading things)
sha256sum (for paranoia)
Root access (because sudo/doas is your friend)
Coffee (not technically required, but highly recommended)

Quick Install

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

# Initialize directories (also prints version)
sudo astral --version

Configuration

Create /etc/astral/make.conf:

# Build flags (adjust for your masochism level)
CFLAGS="-O2 -pipe -march=native"
CXXFLAGS="$CFLAGS"
MAKEFLAGS="-j$(nproc)"

# Enable ccache (because compiling twice is for chumps)
CCACHE_ENABLED="yes"

# Features
FEATURES="ccache parallel-make strip"

Pro tip: -march=native optimizes for your CPU. Don't use it if you're building for other machines, genius.

Basic Usage

Installing Packages

# Install from official repository (AOHARU)
sudo astral -S package-name

# Install from community overlay (ASURA)
sudo astral -SA package-name

# Build from local recipe
sudo astral -C category/package-name

# Install multiple packages in parallel
sudo astral --parallel-build pkg1 pkg2 pkg3

# Resume an interrupted build
sudo astral -Re package-name

Removing Packages

# Remove a single package
sudo astral -R package-name

# Remove multiple packages in parallel
sudo astral -R pkg1 pkg2 pkg3

# Remove package + orphaned dependencies
sudo astral -r package-name

# Remove multiple packages + their orphaned deps in parallel
sudo astral -r pkg1 pkg2 pkg3

# Remove all orphans (spring cleaning!)
sudo astral --autoremove

# Explicit parallel remove commands
sudo astral --parallel-remove pkg1 pkg2 pkg3
sudo astral --parallel-removedep pkg1 pkg2 pkg3

Searching & Information

# Search for packages
astral -s nano

# Show package info
astral -I bash

# Show package info as JSON
astral -I bash --json

# Show dependency tree
astral -D gcc

# Check for broken dependencies
astral -Dc

# Why is this installed?
astral -w readline

# Preview what would be installed (no changes)
astral --preview package-name

# Show USE flags
astral --use
astral --use package-name

# Count packages
astral --count          # all
astral --count aoharu
astral --count installed

# List installed packages
astral -ll
astral -ll --json

# List world set (explicitly installed)
astral -W

# Show build environment
astral --show-env

System Maintenance

# Update repository indexes
sudo astral -u
sudo astral -u aoharu    # specific repo

# Upgrade all packages (grab some coffee)
sudo astral --Upgrade-All

# Clean cache (uninstalled recipes)
sudo astral -Cc

# Rebuild file ownership index
sudo astral -RI

# Generate dependency graph (.dot format)
astral --graph-deps package-name

# Validate a recipe file
astral --validate /path/to/recipe.stars

# Verify installed package file integrity
astral --verify-integrity package-name

# Verify package builds reproducibly
astral --verify-reproducible package-name

# Clean temporary build directories
sudo astral --cleanup-temp

# Check for Astral updates
astral --check-version

# Update Astral itself
sudo astral -U
sudo astral -U dev    # specific branch

# Show current configuration
astral --config

Recipe Formats

Astral supports four recipe formats because we couldn't decide on one and now we're stuck with all four.

Dir Format (Directory Based)

The Ancient format. Messy, spaghetti and deprecated (who uses these?)

Read here

v1 Format (@SECTION)

The OG format. Simple, clean, and deprecated.

VERSION="1.2.3"
DESCRIPTION="A cool package"
HOMEPAGE="https://example.com"

@DEPENDS
gcc
make

@SOURCES
https://example.com/package-1.2.3.tar.gz

@CHECKSUMS
sha256:abc123... package-1.2.3.tar.gz

@BUILD
./configure --prefix=/usr
make -j$(nproc)

@PACKAGE
make DESTDIR="$PKGDIR" install

Use when: You're feeling nostalgic or hate yourself.

v2 Format ($PKG.*)

The current standard. More verbose, more powerful.

$PKG.Metadata: {
    VERSION = "1.2.3"
    DESCRIPTION = "A cool package"
    HOMEPAGE = "https://example.com"
    CATEGORY = "app-editors"
};

$PKG.Depend {
    $PKG.Depend.Depends {
        gcc
        make
        ncurses
    };
};

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

$PKG.Checksums {
    sha256:abc123... package-1.2.3.tar.gz
};

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

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

Use when: You want structure but don't need dependency separation.

v3 Format (Separated Dependencies)

The recommended format. Finally separates build-time and runtime dependencies.

$PKG.Version = "3"

$PKG.Metadata: {
    Version = "1.2.3"
    Description = "A cool package"
    Homepage = "https://example.com"
    Category = "app-editors"
};

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

$PKG.Depend.RDepends: {
    ncurses
    readline
};

$PKG.Depend.Optional: {
    bash-completion
};

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

$PKG.Checksums: {
    sha256:abc123... package-1.2.3.tar.gz
};

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

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

$PKG.PostInstall: {
    # Optional: runs after installation
};

$PKG.PostRemove: {
    # Optional: runs after removal
};

Use when: You want a clean system without build tools polluting your runtime.

Key differences:

BDepends: Build-time only (removed after build)
RDepends: Runtime dependencies (kept forever)
Optional: Nice-to-have features (user choice)
PostInstall / PostRemove: Hooks that run after install/removal

Package Management

The World Set

The "world set" is your list of explicitly installed packages. Think of it as your package wishlist, except you already got everything.

# List world set
astral -W

# World set management
astral --world-add package-name
astral --world-remove package-name
astral --world-show
astral --world-sets          # show available sets (@system, @world)
astral --world-depclean      # world-aware dependency cleaning
astral --calc-system         # calculate @system set

Important: Orphaned packages (not in world, not depended on) can be removed with --autoremove.

Package Holds

Prevent specific packages from being upgraded:

# Hold a package at its current version
astral --hold package-name

# Release the hold
astral --unhold package-name

# See what's held
astral --list-held

Package Masking

Block specific package versions:

# Mask a version range
astral --mask "firefox >= 120.0"

# Unmask
astral --unmask firefox

# /etc/astral/package.mask (manual editing)
broken-package
experimental-tool >= 3.0
old-library < 2.0

Dependency Resolution

Astral uses recursive dependency resolution. It's like a family tree, but with software.

# Preview what will be installed (no changes made)
astral --preview bash

# Interactive dependency selection
astral -S bash
# Shows a tree with:
# [✓✓] - Already installed
# [✓ ] - On host (can skip)
# [  ] - Will install
# [OPT] - Optional

Pro tip: Press Enter to install all, or type numbers to skip (e.g., 1 3 5).

Host Dependencies

Some packages might already be on your system. Astral checks:

pkg-config (most reliable)
Binary in $PATH
Shared library in /lib, /usr/lib, etc.
Your manually configured HOST_PROVIDED list

# Test if a package is provided by the host
astral --host-check gcc

# Show all detected host dependencies
astral --host-deps

Virtual Packages

Virtual packages allow alternatives:

# /etc/astral/virtuals/compiler
gcc
clang
tcc

If you request virtual/compiler, Astral checks if any provider is installed.

# List all virtual package providers
astral --list-virtuals

Dependency System

Dependency Types (v3)

BDepends: Build-time dependencies (gcc, make, cmake)
RDepends: Runtime dependencies (libraries, interpreters)
Optional: Extra features (bash-completion, docs)

Versioned Dependencies

You can specify version constraints:

ncurses >= 6.0
readline = 8.2
python < 3.12

Operators: =, >=, <=, >, <

Circular Dependencies

Astral detects circular dependencies and will yell at you:

ERROR: [pkg-a] CIRCULAR DEPENDENCY DETECTED! Chain: pkg-a -> pkg-b -> pkg-a

Solution: Fix your damn dependencies. Or cry. Both work.

Service Management

Astral has built-in service management that auto-detects your init system. No need to remember which tool your distro uses.

# Start / stop / restart a service
sudo astral start sshd
sudo astral stop sshd
sudo astral restart sshd

# Enable / disable at boot
sudo astral enable sshd
sudo astral disable sshd

# Check service status
astral status sshd

Supported init systems, detected automatically:

systemd - uses systemctl
OpenRC - uses rc-service / rc-update
runit - uses sv / symlinks in /var/service
s6 - uses s6-rc / s6-rc-bundle-update
SysVinit - uses service / update-rc.d / chkconfig

Astral tells you which init system it detected when you run a service command. If it gets it wrong, file a bug.

Configuration

make.conf

Located at /etc/astral/make.conf:

# Compiler flags
CFLAGS="-O2 -pipe -march=native"
CXXFLAGS="$CFLAGS"
LDFLAGS="-Wl,--as-needed"
MAKEFLAGS="-j$(nproc)"

# ccache (compile cache)
CCACHE_ENABLED="yes"
CCACHE_DIR="/var/cache/ccache"
CCACHE_MAXSIZE="5G"

# Features
FEATURES="ccache parallel-make strip"

# Binary packages (not implemented yet, lol)
BINPKG_ENABLED="no"

# Host-provided packages (won't try to install these)
HOST_PROVIDED="gcc make glibc linux-headers"

# Stripping
STRIP_BINARIES="yes"
STRIP_LIBS="yes"
STRIP_STATIC="yes"

# Parallel downloads
ASTRAL_MAX_PARALLEL=4

# Collision detection
COLLISION_DETECT="yes"
GHOST_FILE_CHECK="yes"

astral.stars

Global Astral configuration lives at /etc/astral/astral.stars:

# Create default config
sudo astral --astral-stars-create

# Edit and hot-reload
sudo astral --astral-stars-edit /etc/astral/astral.stars

Advanced Features

Parallel Builds and Removals

Build or remove multiple packages concurrently:

# Install multiple packages in parallel (respects dependency order)
sudo astral --parallel-build pkg1 pkg2 pkg3

# Remove multiple packages in parallel
sudo astral --parallel-remove pkg1 pkg2 pkg3
sudo astral --parallel-removedep pkg1 pkg2 pkg3

# -R and -r also dispatch to parallel automatically when given multiple packages
sudo astral -R pkg1 pkg2 pkg3
sudo astral -r pkg1 pkg2 pkg3

Uses $(nproc) jobs by default.

Parallel Downloads

Downloads up to 4 sources concurrently (configurable):

# In make.conf
ASTRAL_MAX_PARALLEL=4

ccache Support

ccache caches compilation objects. Install once, compile twice at lightning speed.

# Install ccache
sudo astral -S dev-util/ccache

# Enable in make.conf
CCACHE_ENABLED="yes"

# Check stats
astral --ccache-stats

# Clear cache
astral --ccache-clear

Warning: ccache needs disk space. Set CCACHE_MAXSIZE appropriately.

Build State Management

Resume interrupted builds:

sudo astral -Re package-name

Stages: configure → build → package. Resumes from the last successful stage.

Sandbox Isolation

Packages build in an isolated sandbox. Astral picks the best available method:

Bubblewrap (most secure, preferred)
Chroot (requires root)
Fakechroot (userspace isolation, no root needed)
Fakeroot (minimal, better than nothing)

# Test sandbox isolation on your system
sudo astral --sandbox-test

Safety features can be toggled:

# Show status of all safety features
astral --safety-status

# Enable/disable specific features (script-check, collision, etc.)
sudo astral --on script-check
sudo astral --off collision

Ghost File Detection

Detects files installed outside $PKGDIR (packaging bugs). Automatically checked during installation - shows a warning if a package recipe tries to install directly to /usr.

What to do: File a bug. The recipe is broken.

Atomic Installation

Packages are installed atomically. Either everything succeeds, or nothing happens.

Benefits:

No half-installed packages
Safe interruption (Ctrl+C won't wreck your system)
Automatic rollback on failure

JSON Output

Several commands support --json for scripting:

astral -s package-name --json
astral -I package-name --json
astral -ll --json

Chroot

# Chroot into a directory (e.g. a new Astaraxia install)
sudo astral --chroot /mnt/astaraxia

Security Features

GPG Signing

# Import a repository GPG key
sudo astral --import-key https://example.com/repo.asc

# Verify a file's GPG signature
astral --verify-sig /path/to/file.tar.gz

# Generate a new GPG signing key
sudo astral --gpg-gen-key "My Signing Key"

# List managed keys
astral --gpg-list-keys

# Set trust level (unknown|never|marginal|full|ultimate)
sudo astral --gpg-set-trust <key-id> full

# Generate a revocation certificate
astral --gpg-revoke <key-id>

# Rotate signing key
sudo astral --gpg-rotate <old-key-id> <new-key-id>

# Build Web of Trust graph
astral --gpg-wot

Certificate Pinning

Pin HTTPS certificates for extra paranoia:

# Pin a host's certificate
sudo astral --pin-cert example.com
sudo astral --pin-cert example.com:443

# Verify a pinned certificate hasn't changed
astral --verify-cert example.com

File Integrity Monitoring (FIM)

Track file hashes and detect unauthorized changes:

# Record a file's current hash
sudo astral --fim-record /etc/passwd

# Check if a file has changed since recording
astral --fim-check /etc/passwd

# Scan all tracked files at once
astral --fim-scan

Audit Trail

Recipe audit log for accountability:

# Query the audit log
astral --audit-query

# Verify a recipe's audit trail
astral --audit-verify package-name

Lock System

# Show current lock status (who's holding it, for how long)
astral --lock-info

# Test the lock system
astral --lock-test

Transactions & Rollback

Every install/remove operation is a transaction. Nothing is permanent until it commits.

# List transactions
astral --transactions          # all
astral --transactions active
astral --transactions committed

# Roll back a specific transaction by ID
sudo astral --rollback <transaction-id>

# Recover from incomplete/interrupted transactions
sudo astral --recover

How it works: Before any operation, Astral snapshots the DB and all affected paths. If something goes wrong (power cut, Ctrl+C, build failure), --recover finds incomplete transactions and rolls them back automatically.

Note: This is Astral's package-level transaction system, separate from astral-env's system-level rollback.

Recipe Generator

astral-recipegen

Generates .stars recipes so you don't have to type boilerplate.

Interactive Mode

astral-recipegen interactive v3

Prompts for package name, version, description, dependencies, and build system.

Auto-Detection

astral-recipegen auto nano https://nano-editor.org/dist/v8/nano-8.2.tar.xz

Does the following automatically:

Downloads source
Detects build system (autotools/cmake/meson/python/make)
Extracts version from filename
Generates checksum
Creates v3 recipe

Magic: It actually works most of the time.

Template Generation

astral-recipegen template cmake v3 -o mypackage.stars
astral-recipegen template python v2
astral-recipegen template autotools v3
astral-recipegen template meson v3
astral-recipegen template make v3

Converting Directory Recipes

astral-recipegen dir-to-stars /usr/src/astral/recipes/app-editors/nano

Migration

# Migrate v1/v2 → v3
astral-recipegen migrate mypackage.stars v3

# Convert between any versions
astral-recipegen convert mypackage.stars v2

From PKGBUILD (Experimental)

astral-recipegen from-pkgbuild /path/to/PKGBUILD v3

Converts Arch Linux PKGBUILDs. Results may vary. Always review manually.

Git Support

astral-recipegen git

Troubleshooting

"Another instance of astral is already running" / Stale Lock

# Check if actually running
ps aux | grep astral

# Show lock info
astral --lock-info

# Remove stale lock manually (only if astral is definitely not running)
sudo rm -rf /var/lock/astral.lock.d

"Package version X.Y.Z is MASKED"

# Check why
cat /etc/astral/package.mask

# Unmask if you're brave
astral --unmask package-name

"CIRCULAR DEPENDENCY DETECTED"

Fix the recipes. You can't install A if A depends on B and B depends on A. It's turtles all the way down.

"Checksum mismatch"

Causes: Source file changed upstream, network corruption, or a very bad day (MITM).

# Re-download
rm /var/cache/astral/src/*

# Update checksum in recipe if source changed upstream
sha256sum /var/cache/astral/src/package-1.2.3.tar.gz

"Failed to download source"

Check your internet connection (turn it off and on again)
Try again later
Update the recipe with a working mirror

Build fails with "command not found"

Missing build dependency.

astral -D package-name        # check dependency tree
sudo astral -S missing-dep    # install what's missing

Interrupted build / half-installed package

# Resume from last successful stage
sudo astral -Re package-name

# Or recover all incomplete transactions
sudo astral --recover

Service command fails / wrong init system detected

# Check what Astral thinks your init system is
astral status any-service-name
# Output includes "Using init system: <name>"

If it's wrong, file a bug with your /proc/1/comm output.

Debugging

# Verbose output
sudo astral -v -S package-name

# Check build logs
ls /tmp/astral-build-*

# Check sync logs
tail -f /var/log/astral_sync_*.log

# Run test suite
sudo astral --test all
sudo astral --test quick

Contributing

Writing Recipes

Use v3 format (it's the future, embrace it)
Separate dependencies (BDepends vs RDepends)
Test your recipe before submitting
Use descriptive commit messages ("fixed stuff" is not descriptive)

Recipe Guidelines

Checksums are mandatory (we're paranoid for a reason)
Use $PKGDIR for installation (never install directly to /)
Strip binaries unless there's a good reason
Clean up (remove docs/examples if nobody reads them)
PostInstall/PostRemove hooks for anything that needs to happen after the files land

Submitting to ASURA

ASURA is the community overlay.

# Fork the repository
git clone https://codeberg.org/Izumi/ASURA

# Add your recipe
cd ASURA/recipes
cp your-recipe.stars category/package-name.stars

# Commit and push
git add .
git commit -m "Add package-name-1.2.3"
git push

Contributing to Astral Core

Read the code (good luck - it's 10k lines of sh)
Test your changes (seriously)
No bashisms - POSIX sh only
Submit a PR
Wait for the One Maniac™ to review (may take up to 3 business weeks)

FAQ

Why POSIX sh?

Because if /bin/sh isn't working, you have bigger problems than package management.

Why not just use [insert package manager here]?

Because we're special snowflakes who compile from source.

Does Astral support binary packages?

Technically yes (BINPKG_ENABLED="no" in the config), but actually no. Not yet.

Can I use Astral on [insert distro here]?

Probably. It's POSIX-compliant. Your mileage may vary.

Why four recipe formats?

Legacy reasons. We couldn't break backwards compatibility without angering the three people using v1.

Is Astral stable?

Define "stable". It won't delete your /usr anymore, so... yes?

How do I pronounce "Astral"?

Like "astral projection", but for packages.

What's the difference between AOHARU and ASURA?

AOHARU: Official, manually reviewed, trusted
ASURA: Community-contributed, use at your own risk

Do I need to review recipes?

For AOHARU: No, we review them.
For ASURA: YES, ALWAYS. Never run untrusted code as root.

What's astral-env?

It's the declarative system configuration layer that sits on top of Astral. It lets you describe your entire system - packages, services, dotfiles, snapshots - in a .stars file and apply it all at once. Read the astral-env docs.

Who maintains this?

One Maniac. Just one. Send help (or coffee).

Credits

Created by: One Maniac™
Inspired by: Gentoo Portage, Arch Pacman, KISS Linux, and pain
Special thanks: Everyone who reported bugs instead of rage-quitting (both of you)

License

Just plain GPL-3.0

Final Notes

"Astral: Because life's too short to not compile everything from source"

Nobody, ever

Astral is still evolving. The code is still spaghetti. The philosophy is still based. The implementation is extremely transparent (you can read all 10,000+ lines of it).

If you made it this far, congratulations. You're either very thorough, very bored, or writing documentation for a One Maniac™ project at 2am. Either way, happy compiling.

Last updated: 06 March 2026 (GMT+8)
Documentation version: 5.0
Sanity level: Questionable, as always

Name		Name	Last commit message	Last commit date
Latest commit History 199 Commits
completions		completions
.stars.md		.stars.md
Dir.md		Dir.md
LANG-CHOICES.md		LANG-CHOICES.md
LICENSE		LICENSE
NoRecipes.md		NoRecipes.md
README.md		README.md
astral		astral
astral-recipegen		astral-recipegen
astral-recipegen Docs.md		astral-recipegen Docs.md

Folders and files

Latest commit

History

Repository files navigation

Astral Package Manager Documentation

Table of Contents

Introduction

What is Astral?

Why Astral?

Why Not Astral?

Installation

Prerequisites

Quick Install

Configuration

Basic Usage

Installing Packages

Removing Packages

Searching & Information

System Maintenance

Recipe Formats

Dir Format (Directory Based)

v1 Format (@SECTION)

v2 Format ($PKG.*)

v3 Format (Separated Dependencies)

Package Management

The World Set

Package Holds

Package Masking

Dependency Resolution

Host Dependencies

Virtual Packages

Dependency System

Dependency Types (v3)

Versioned Dependencies

Circular Dependencies

Service Management

Configuration

make.conf

astral.stars

Advanced Features

Parallel Builds and Removals

Parallel Downloads

ccache Support

Build State Management

Sandbox Isolation

Ghost File Detection

Atomic Installation

JSON Output

Chroot

Security Features

GPG Signing

Certificate Pinning

File Integrity Monitoring (FIM)

Audit Trail

Lock System

Transactions & Rollback

Recipe Generator

astral-recipegen

Interactive Mode

Auto-Detection

Template Generation

Converting Directory Recipes

Migration

From PKGBUILD (Experimental)

Git Support

Troubleshooting

"Another instance of astral is already running" / Stale Lock

"Package version X.Y.Z is MASKED"

"CIRCULAR DEPENDENCY DETECTED"

"Checksum mismatch"

"Failed to download source"

Build fails with "command not found"

Interrupted build / half-installed package

Service command fails / wrong init system detected

Debugging

Contributing

Writing Recipes

Recipe Guidelines

Submitting to ASURA

Contributing to Astral Core

Packages