penguins-eggs-legacy: the shell-script generation of a Linux remastering tool

Why a legacy repository still gets commits

The reason this project exists is written in its own README, and it is unusual to see stated so plainly. After years of passionate work on penguins-eggs, the author is now undertaking its next evolution: the old good penguins-eggs became penguins-eggs-legacy, and there is now a separate penguins-eggs. The new one is built on oa, a high-performance C-native remastering engine, and coa, its intelligent Go orchestrator. The new architecture replaces fragile bash scripts with native Linux kernel syscalls and strict zero-copy principles.

So this repository is the previous generation, and the reason it still receives commits is that it still does something the new one does not yet do. The stated goal of the new engine is a truly universal approach to Linux remastering, on the observation that every distribution is different yet they all share common roots, and oa-tools already supports Alpine, Arch, Debian, Fedora, Manjaro and openSUSE, with the aim of proving that a single unified engine can handle them all. The legacy tree covers a wider set of distributions, and it covers the older ones.

The project describes itself as a professional and universal remastering tool for all major distributions, and the pun is the house style: penguin's eggs are generated and new birds are ready to fly. The homepage is penguins-eggs.net, and the README links a separate AI context file at penguins-eggs.net/llms.txt, which tells you the project is being maintained with that audience in mind.

The maintenance is real rather than archival. The recent releases are v26.9.29 marked Maintenance from 2026-09-29, v26.5.12 from 2026-05-12 and v26.3.21 from 2026-03-21, and the last push was on 2026-10-06 with the project not archived. The version numbering follows a year and month scheme, which is a convention you will see across the author's tools.

What the tool actually does

The functional description is short. penguins-eggs, or simply eggs, is a console tool that allows you to remaster your system and redistribute it as live images on USB sticks or via PXE. The README frames it as a way to hatch a new system from an existing one, and calls it a system cloning and distribution remastering tool primarily designed for Linux, allowing users to create customized live ISO images or backups of a Linux system, replicating the setup easily.

The capabilities list breaks that into four.

Distribution remastering is the headline use: craft your own Linux distro or a spin of an existing one, tweak an existing system, strip or add components, and package it as a new ISO.

System backup and cloning creates a snapshot of your current system, including installed packages and configurations.

Distro-agnostic operation works across Debian, Devuan, Ubuntu, Arch, Fedora, AlmaLinux, Rocky, OpenSuSE and Alpine.

Multi-architecture support covers Debian and Ubuntu packages released for i386, amd64, arm64 and riscv64, with the riscv64 described as native recursive remastering.

Two implementation details are worth singling out. The tool leverages OverlayFS to avoid physically copying the entire filesystem, combined with zstd compression, which the README says is up to 10x faster. And it supports LUKS encryption for user data within the ISO, which is the difference between a spin that leaks the contents of the home directory to anyone who boots it and one that does not.

The OverlayFS point deserves a second look, because it is where most of the speed claim comes from. A remaster that physically copies a root filesystem spends most of its time in IO, and the same code path has to deal with a copy that is now a separate artefact to keep consistent. Avoiding the copy changes the failure modes as well as the timing.

Installing it, and the two routes on offer

There are two installation methods and the choice is between convenience and integration.

The recommended one is the Fresh Eggs script, described as the most practical way suitable for all supported distros. It automatically configures necessary repositories like NodeSource and installs dependencies, and the command sequence is:

git clone [https://github.com/pieroproietti/fresh-eggs](https://github.com/pieroproietti/fresh-eggs)
cd fresh-eggs
sudo ./fresh-eggs.sh

The second route is native packages, with a specific repository or channel per distribution family.

For Debian and Ubuntu there is an install guide and a PPA page. For Arch and Manjaro it is available in the AUR and in the Manjaro Community repository, with the commands `yay penguins-eggs` or `pamac install penguins-eggs`. For Fedora and RHEL there are separate guides for Fedora and for Enterprise Linux. For Alpine there is a dedicated penguins-alpine repository.

The spread across four package ecosystems is the clearest single indicator of what this tool is for. A tool that installs itself cleanly from the distribution's own channels is a tool that people are expected to run on a desktop they already have, and the fact that the same tool is packaged for AUR, a PPA, Fedora and an Alpine repository means the author expects it to be used on whatever machine a user happens to have.

Note the binary name difference. The package on npm is penguins-eggs, the package.json names the project penguins-eggs-legacy with a shortName of eggs-legacy, and the bin entry maps eggs-legacy to ./bin/run.js. The command line is therefore eggs-legacy, and the repository also contains an eggs script and a release script at the top level, so a working directory may contain several similarly named entry points. That is exactly the kind of detail that a rename leaves behind, and it is worth knowing before you file a bug about a command that is not found.

Producing a clean image versus keeping your data

The usage section starts simply. Once installed, you run eggs to see the available commands, and the basic case is described as creating a distributable live ISO without user data, which the README calls perfect for sharing your custom distro:

sudo eggs produce

That distinction is the important one. A clean ISO contains the system as configured but not the people who built it. A clone contains the users, their files, their keys and their browser history. The README presents the cloning path as a table of goals and commands, and the header for that table is To keep your user data, configurations, and files.

The two outputs have very different audiences and very different risks. The clean ISO is a distribution artefact, something you publish and other people install. The clone is a backup, and the reason a tool like this exists for backup as well as for distribution is that a running system is full of state that no package manager reconstructs: local configuration, custom services, data in volumes, credentials.

The documentation also notes that the tool is a console tool and that the project ships a GUI and a book, both listed in the table of contents along with the Aviary of tools and terminology. The GUI is a separate front end, and the presence of a packaged book rather than a wiki suggests the author treats the tool as something people need to be taught rather than something they can infer from a help screen.

The rest of the documentation links are the ones to expect for a project of this size: a blog, a tutorial called Cook eggs in 5 minutes, a users guide, an FAQ and a changelog, plus a basket of downloadable images and a Google Drive folder, and distribution through SourceForge and npm.

The TypeScript rewrite, and the pile of shell that came with it

The repository layout explains the engineering history better than the README does, because it mixes a modern Node toolchain with a large amount of system-level shell.

The TypeScript side is an oclif project. The package.json dependencies show the shape: @oclif/core with the help, version and autocomplete plugins, @inquirer/prompts and inquirer for prompts, chalk and cli-cursor for terminal output, ink with ink-progress-bar and ink-spinner for the terminal interface, and react at 19.3.0, which is what ink renders with. There is express, axios, ws and tftp, the last of which is a hint at the PXE side of the tool. There is js-yaml and mustache for configuration and templating, and bcryptjs, cors, netmask, systeminformation and debug as supporting pieces. The dev dependencies include @oclif/test, chai, mocha and @types packages, and there is a .mocharc.json at the root, so the test runner is Mocha.

The rest of the tree is the older generation left in place. There is actualize.sh at the root, debug-img.sh, install-pnpm9.sh, nodesource_setup.sh, nvm-setup and resyd, which are the kind of scripts that accumulate in a project that started as shell. There are directories for architectures/, addons/, bin/, conf/, dracut/, mkinitcpio/, mkinitfs/, eui/, perrisbrewery/, spacemit/, packaging/ and scripts/, plus manpages/ and a connect script. The dracut, mkinitcpio and mkinitfs directories are the boot-time initramfs generators, which tells you the tool builds boot media rather than only copying files.

There is also an Assets/ directory, an eslint.config.js, a .prettierrc alongside a .prettierrc.json, a pnpm-workspace.yaml with a pnpm-lock.yaml, and a separate .oclif.manifest.json, which is oclif's generated command index. The presence of both package-lock conventions in the tree, the pnpm lock and the install-pnpm9.sh script, says the project migrated to pnpm 9 at some point and kept both histories around.

The KEYS.asc file and the packaging/ directory point to the release machinery, since the tool publishes to the AUR, a PPA, Fedora and Alpine repositories and that needs a signing key per channel.

How to evaluate it, and which version you should actually install

There is one decision to make before anything else, and the README makes it: legacy or new.

If you are starting fresh and your distribution is one that oa-tools already supports, namely Alpine, Arch, Debian, Fedora, Manjaro or openSUSE, the newer penguins-eggs is the direction the author is taking, and the legacy repository is where you go when the new engine does not cover your case yet. The legacy project also covers distributions the new one does not list, and it is the one with a longer published history of working installs.

If you do choose the legacy line, the two installation routes carry different operational implications. The Fresh Eggs script clones a repository and runs a script with sudo, and it configures repositories and installs dependencies for you, which is convenient and means you are trusting a script to modify your system. The native package route is a smaller commitment: your distribution's package manager installs a known artefact, and the upgrades come through the channel you already trust. For a machine you care about, the native route is the better default even though the script is the recommended one.

Two further checks. First, the architecture support is uneven by design. The multi-architecture line covers Debian and Ubuntu for i386, amd64, arm64 and riscv64, with riscv64 called out as native recursive remastering, so on a less common architecture you should confirm which path your distribution is on. Second, the encryption feature matters more than it sounds. LUKS support for user data inside the ISO is what separates a spin you can hand to someone else from one that carries your home directory in the clear, and a clone without it is not a backup you would want on a USB stick.

And the licence is worth a look. The repository records a custom licence that GitHub cannot classify, and the project is GPL-based in its lineage, so read the LICENSE file before you redistribute an image built with it, particularly if the image contains third-party packages whose own terms apply.

Editorial conclusion

Adopt penguins-eggs-legacy if you need to remaster a Linux distribution the newer oa engine does not cover yet, or if you want the longer established install path, and if your distribution is one of Debian, Devuan, Ubuntu, Arch, Fedora, AlmaLinux, Rocky, openSUSE or Alpine. Do not adopt it for a new project on a distribution that oa-tools already supports, because the author is explicitly developing that engine as the successor and the legacy tree will not gain the new features. Before you commit, decide between the Fresh Eggs script and the native package route, since the script runs with sudo and modifies your system while the package route installs a known artefact through a channel you already trust, and confirm that LUKS encryption is enabled for any clone that carries user data.

Frequently asked questions

Official sources

1. Issues
2. pieroproietti/penguins-eggs-legacy on GitHub
3. Project website
4. README
5. Releases