[update-readmes] Mode: rewrite — migrating to template structure...

immutable-linux-framework

This project provides a framework for building immutable Linux distributions that is both distro-agnostic and architecture-agnostic. It is designed for developers and system integrators who need a consistent, reproducible, and secure foundation for creating and managing Linux-based systems. The framework includes tools for configuration, diagnostics, ISO generation, and system updates.

Architecture

The framework consists of modular components designed to build and manage immutable Linux distributions. Key components include:

1. Core Tools: Implements the primary logic for creating and managing immutable systems. Written in Go, it includes a CLI (ilf) for operations like building, testing, and deploying configurations.
2. Configuration Files: Defines system behavior and distribution-specific settings using TOML and YAML files located in the configs/ and distros/ directories.
3. Systemd Integration: Provides service and timer units in systemd/ for automated updates and maintenance tasks.
4. Build Scripts: The Makefile orchestrates build, install, and test processes using Go tooling.
5. AI Agent: A Node.js-based component (eggs-ai) for diagnostics, ISO building, and configuration assistance. It is located in the bin/ and dist/ directories.

The directory structure is as follows:

.
├── bin/                # Executable scripts
├── configs/            # Configuration templates
├── distros/            # Distribution-specific settings
├── doc/                # Documentation
├── systemd/            # Systemd service and timer files
├── tools/              # Go source code for core tools
├── dist/               # Compiled Node.js outputs
├── src/                # Source code for eggs-ai
├── Makefile            # Build and install instructions
├── go.mod              # Go module dependencies
└── package.json        # Node.js dependencies and scripts

Components interact via configuration files, systemd services, and CLI commands, enabling a modular and extensible framework.

Install

git clone https://github.com/Interested-Deving-1896/immutable-linux-framework.git
cd immutable-linux-framework

Usage

Configuration

CI

The repository uses GitHub Actions for continuous integration. Below are the workflows and their purposes:

• build.yml: Builds the project binaries for supported architectures. No secrets required.
• test.yml: Runs unit and integration tests for the project. No secrets required.
• lint.yml: Checks code formatting and style using golangci-lint and eslint. No secrets required.
• deploy-book.yml: Deploys documentation to the project’s website. Requires DOCS_DEPLOY_KEY secret.
• mirror-artifacts.yml: Mirrors build artifacts to external storage. Requires MIRROR_STORAGE_KEY secret.
• sync-to-gitlab.yml: Synchronizes the repository with a GitLab mirror. Requires GITLAB_TOKEN secret.
• ota-self-update.yml: Automates over-the-air updates for supported distributions. No secrets required.
• validate-readme-render.yml: Validates the rendering of README files. No secrets required.

Secrets must be configured in the repository settings for workflows requiring them.

Mirror chain

This repo is maintained in Interested-Deving-1896/immutable-linux-framework and mirrored through:

Interested-Deving-1896/immutable-linux-framework  ──►  OpenOS-Project-OSP/immutable-linux-framework  ──►  OpenOS-Project-Ecosystem-OOC/immutable-linux-framework

Changes flow downstream automatically via the hourly mirror chain in fork-sync-all. Direct commits to OSP or OOC are detected and opened as PRs back to Interested-Deving-1896.

Contributors

@Interested-Deving-1896 - 518 commits

Origins

Original project — no upstream fork.

Resources

No additional resource files found.

License

MIT © 2026 Interested-Deving-1896