MujaOS — Modular NixOS Configuration

Declarative. Modular. Reproducible.

A lightweight, flake-based NixOS configuration designed for modern systems and developers who value clarity, speed, and control.

🧩 Overview

MujaOS is more than just a NixOS configuration — it’s a framework for reproducible Linux environments. Built on the power of Nix flakes, MujaOS turns the complex world of system configuration into something elegant, scalable, and maintainable.

Whether you’re setting up a personal workstation, deploying servers, or managing multiple devices, MujaOS ensures every build is identical, version-controlled, and clean.

Goal: Deliver a modern, opinionated foundation for NixOS that balances flexibility with simplicity — perfect for both enthusiasts and professionals.

⚙️ Why MujaOS?

MujaOS bridges the gap between Nix purity and developer pragmatism, making it accessible and production-ready.

🧠 Core Architecture

MujaOS is built with three key layers, making it modular yet cohesive:

1. Flake Root (flake.nix) — the project entrypoint defining dependencies, inputs, and outputs.
2. Modules Layer (modules/) — independent building blocks for services, networking, security, and UI.
3. Hosts Layer (hosts/) — defines individual systems (e.g., laptop, server, desktop) as unique compositions of modules.

Add optional layers for:

• Users (users/) — personalized development environments
• Overlays (overlays/) — extend or override package definitions

This design keeps your infrastructure composable, reusable, and easy to reason about.

🧩 Every host is just a collection of modules — plug in, remove, or swap components without breaking the system.

✨ Features at a Glance

• ⚙️ Flake-based design — self-contained, modern, and version-controlled
• 🧩 True modularity — services, hardware, and users separated cleanly
• 🌐 Multi-host management — run servers, desktops, and VMs from one repo
• 🔒 Security-focused defaults — hardened settings out of the box
• 🔁 Reproducible builds — deterministic and rollback-ready
• 🧰 User profiles — tailor user environments with zero overlap
• 🪶 Minimal boilerplate — human-readable structure built to scale

🚀 Getting Started

1. Clone the repository

git clone https://github.com/mujaaco/mujaos.git
cd mujaos

2. Switch to your host configuration

sudo nixos-rebuild switch --flake .#laptop --show-trace

Replace laptop with your host name (e.g. server, desktop, or workstation).

3. Reboot & enjoy

Once complete, reboot to load your fully declarative system.

💡 New to NixOS? Check out Nix Pills or the NixOS Flakes Wiki.

🧭 Project Structure

mujaos/
├── flake.nix              # Main flake entrypoint
├── flake.lock             # Dependency lock file
├── hosts/                 # Host-specific definitions
│   ├── laptop/
│   └── server/
├── modules/               # Modular system components
├── users/                 # User configurations
├── overlays/              # Custom package overrides
├── assets/                # Images and docs
└── README.md              # Project documentation

Clean. Predictable. Extensible. You can add or remove hosts without affecting others — every system stays isolated yet maintainable.

🧰 Example Commands

Rebuild or switch configurations:

sudo nixos-rebuild switch --flake .#desktop

Update inputs (Nixpkgs, Home Manager, etc.):

nix flake update

Test changes without applying:

sudo nixos-rebuild test --flake .#server

Rollback to previous generations:

sudo nixos-rebuild rollback

💬 Philosophy

MujaOS is founded on three principles:

• Declarative by Design — Systems should describe what they are, not how to become that.
• Modular by Default — Small, composable modules are easier to maintain.
• Reproducible Forever — Your system today should be buildable tomorrow — byte-for-byte identical.

“If it can’t be rebuilt exactly, it’s not truly declarative.”

📈 Roadmap

Upcoming Enhancements:

• 🧩 Plug-and-play desktop environments (GNOME, KDE, Hyprland)
• ☁️ Remote provisioning via SSH and NixOps integration
• 🔄 Template generator for new hosts and modules
• 🧠 Documentation site with interactive examples
• 🧰 Cross-platform build support (x86_64 & aarch64)

💬 Want to shape MujaOS? Join discussions on GitHub Issues.

🤝 Contributing

Contributions are welcome! If you believe in modular, reproducible systems, here’s how to help:

• 🐛 Report bugs — create an issue
• 💡 Suggest features — ideas that enhance maintainability or developer experience
• 🔧 Submit pull requests — keep commits atomic and follow conventional commits style (feat:, fix:, docs:, etc.)

Contributions are reviewed with clarity, modularity, and reproducibility in mind.

📜 License

Licensed under the MIT License — you’re free to use, modify, and distribute under the same terms.

MujaOS — Declarative. Modular. Reproducible. Built with ❤️ for the NixOS and open-source community.