Skip to main content

Quick Start

Install​

Packages are built automatically for every supported family. Download the latest from GitHub Releases or add the official repository:

sudo eggs tools repo add

From source​

git clone https://github.com/pieroproietti/penguins-eggs.git
cd penguins-eggs
make
sudo make install

Requirements: gcc, make, golang 1.25+, git.

Your first ISO in three commands​

# 1. Prepare the system (install squashfs-tools, xorriso, etc.)
sudo eggs tools repo add

# 2. Remaster the running system into a live ISO
sudo eggs remaster

# 3. Find your ISO
ls /home/eggs/*.iso

That's it. The ISO is hybrid (BIOS + UEFI) and ready to boot from USB or in a VM.

Common workflows​

Customize the desktop with penguins-tailor, then remaster​

You can configure and dress your system with ready-made desktop configurations ("costumes") and accessories before remastering using the companion tool penguins-tailor (tailor). Costumes are retrieved from wardrobe ateliers (such as the main atelier pieroproietti/penguins-wardrobe or Charlie Martinez's charliemartinez/penguins-wardrobe):

# 1. Download or update costumes from the atelier
tailor get

# 2. List available costumes
tailor list

# 3. Apply a costume (e.g. colibri)
sudo tailor wear colibri

# 4. Remaster the tailored system into a live ISO
sudo eggs remaster

Graphical desktop experience with penguins-gui​

If you prefer a desktop application, you can use penguins-gui: an independent desktop GUI for penguins-eggs written in Go with the Fyne toolkit. It lets you:

  • Select remaster modes (Standard Live, System Clone, or Crypted Clone with graphical passphrase dialogs);
  • Monitor build output in real time with copy and clear actions;
  • Locate and open the produced ISO folder with xdg-open;
  • Install penguins-eggs CLI and Calamares (with Qt5/Qt6 dependencies) directly from the menus;
  • Run maintenance tasks (update /etc/skel, configure grub40, clean remnants, kill staging).

Customize compression and ISO naming​

# Open the interactive configuration TUI
sudo eggs config

Change the live user password, the compression algorithm (zstd/xz/lz4/gzip), the compression level, the ISO filename prefix, and edit the custom exclude list — all from a single interface. Settings are saved to /etc/penguins-eggs.d/custom.yaml and applied automatically on the next eggs remaster.

Remaster with LUKS encryption (Debian family)​

sudo eggs remaster --crypted

An interactive TUI lets you choose the passphrase and crypto parameters. The resulting ISO boots into a LUKS-encrypted live environment.

Install to disk from the live ISO​

# GUI (requires Calamares and a display server)
sudo eggs sysinstall calamares

# TUI (works on console, serial, ssh)
sudo eggs sysinstall krill

# Coexist multi-boot mode
sudo eggs sysinstall krill --coexist

Debug a remaster problem​

# Stop after a specific step, leaving the chroot mounted for inspection
sudo eggs remaster --stop-after initramfs

# Print the JSON flight plan without building anything
sudo eggs remaster --debug

# Clean up after a failed or interrupted remaster
sudo eggs destroy

Boot an ISO from the hard drive (no USB needed)​

# Generate a GRUB loopback entry for any Linux ISO
eggs tools grub40 /path/to/my.iso

# Write it directly into /etc/grub.d/40_custom
sudo eggs tools grub40 /path/to/my.iso --write
sudo update-grub

Connect with AI Agents (MCP)​

# Enable MCP server and configure AI clients (Antigravity, Claude, Roo-Cline, Cursor, Zed)
sudo eggs mcp enable

# Check status of MCP integration
eggs mcp status

Once enabled, your AI assistant can discover penguins-eggs tools and remaster your system or inspect configuration on demand.

Supported distributions​

penguins-eggs detects the host automatically. Currently supported families:

FamilyExamples
AlpineAlpine Linux
ArchArch Linux, EndeavourOS, Garuda
DebianDebian, Ubuntu, Pop!_OS, Linux Mint, Kali, MX Linux
FedoraFedora, Nobara (recommended: SELINUX=permissive in /etc/selinux/config)
ManjaroManjaro, BigLinux
openSUSEopenSUSE Tumbleweed

Fedora Note: On Fedora systems, it is recommended to set SELINUX=permissive in /etc/selinux/config (or run sudo setenforce 0) to avoid unexplained permission blocks during remastering.

Adding a new distribution requires only a new template module directory under brain.d/modules/ — no Go or C changes.

Where to go next​