v....

Introduction

Everything you need to know to get up and running quickly.


Installation

Download the latest ISOs here: Download Page


How To


Profile Management

Zyphor OS provides an integrated Profile Management feature through Zyphor Command Center, allowing users to personalize and manage their system profile with ease. Users can update their profile information and upload a custom profile image that is automatically optimized for system use. The selected profile image is synchronized across the desktop environment, including the Start Menu panel icon and the LightDM login screen, providing a more personal and consistent user experience throughout Zyphor OS.

Manage Firewall

Zyphor OS uses UFW (Uncomplicated Firewall) to provide a simple and reliable way to manage firewall rules and protect your system from unauthorized network access.

Enable the Firewall

Turn on the firewall to start protecting your system from unauthorized incoming connections.

sudo ufw enable
Check Firewall Status

Check whether the firewall is active and view the currently configured firewall rules.

sudo ufw status
Allow a Port

Allow incoming connections to a specific port. For example, the following command allows SSH connections on port 22.

sudo ufw allow 22/tcp
Deny a Port

Block incoming connections to a specific port.

sudo ufw deny 22/tcp
Remove a Firewall Rule

Remove an existing firewall rule when it is no longer needed.

sudo ufw delete allow 22/tcp
Disable the Firewall

Temporarily disable UFW if firewall protection is not required.

sudo ufw disable

Custom Packages


Zyphor CLI

Installation: zyphor pkg install zyphor-cli

Zyphor CLI Abstraction Layer — A unified command framework that transforms complex Linux operations into simple, consistent, and easy-to-remember commands for developers, administrators, and everyday users.

zyphor help
Showing all commands
Category Command Description
SYSTEM sudo zyphor system upgrade Upgrade all installed system packages to their latest available versions from configured repositories, ensuring security updates, bug fixes, and feature improvements are applied.
SYSTEM sudo zyphor system clean Remove package caches, unused dependencies, residual configs, old logs, and temporary files to free disk space and keep the system optimized.
SYSTEM sudo zyphor system clean --dry-run Preview which unused packages and residual configs would be removed. Nothing is changed.
SYSTEM sudo zyphor system clean --deep Run the standard cleanup, then also empty the user's Trash and remove unused Flatpak runtimes.
SYSTEM sudo zyphor system info Display detailed information about the operating system, kernel version, hardware resources, and system environment.
SETUP sudo zyphor setup dev <target> Automatically configure a complete development environment for the selected programming language or technology stack.
SETUP zyphor setup dev version php List the PHP versions that are installed and available, and show which one is currently active.
SETUP sudo zyphor setup dev version php 8.3 Install the chosen PHP version (e.g. 8.3) with the common extensions and switch the active php command to it. Offers to add the Sury PHP repository if the version is not available in your current sources.
SETUP zyphor setup dev version node Show the installed Node.js version and the latest release of each recent Node.js major version, with LTS releases marked.
SETUP sudo zyphor setup dev version node 22 Install the chosen Node.js version (e.g. 22) and switch to it. A minor version such as 22.5 is also accepted and pinned when it is still available.
SETUP sudo zyphor setup dev android-studio Install and configure Android Studio and Flutter for development, including the Android SDK, required build packages, and PATH entries in your shell configuration.
SETUP sudo zyphor setup dev undo php Remove PHP and its extensions, with optional removal of Composer and the Sury PHP repository. Asks for confirmation before anything is removed.
SETUP sudo zyphor setup dev undo node Remove Node.js, with optional removal of the NodeSource repository files.
SETUP sudo zyphor setup dev undo composer Remove Composer from /usr/local/bin.
SETUP sudo zyphor setup dev undo git Remove the Git settings configured by the setup, with an optional, separate prompt for each generated SSH key. Git and OpenSSH themselves stay installed.
SETUP sudo zyphor setup dev undo android-studio Remove Android Studio, Flutter, and the PATH entries added to your shell configuration, with optional removal of the Android SDK and related build packages.
SETUP sudo zyphor setup dev undo os Remove the OS/Distro development tools installed by setup dev os. Packages the base system depends on, such as gzip, python3, and grub-pc-bin, are kept.
SETUP sudo zyphor setup pentest recon Install reconnaissance and scanning tools such as Nmap, Masscan, Amass, and Gobuster for network and target discovery.
SETUP sudo zyphor setup pentest web Install web application testing tools including Sqlmap, Nikto, Burp Suite, ZAP, and Wpscan for auditing web apps.
SETUP sudo zyphor setup pentest wireless Install wireless auditing tools such as Aircrack-ng, Kismet, and Wifite for testing Wi-Fi networks you own or are authorized to assess.
SETUP sudo zyphor setup pentest passwords Install password auditing tools including John the Ripper, Hashcat, Hydra, and Medusa for credential strength testing.
SETUP sudo zyphor setup pentest sniffing Install traffic analysis tools such as Wireshark, Tcpdump, and Bettercap, and configure non-root packet capture.
SETUP sudo zyphor setup pentest forensics Install forensics and analysis tools including Autopsy, Sleuth Kit, Binwalk, and Volatility3 for investigating systems and files.
SETUP sudo zyphor setup pentest exploitation Install exploitation framework tools such as Metasploit, Exploit-DB, and SET for authorized penetration testing engagements.
SETUP sudo zyphor setup pentest full Install the complete pentest toolkit, covering recon, web, wireless, passwords, sniffing, forensics, and exploitation in one run.
SETUP sudo zyphor setup wine Install and configure Wine with 32-bit compatibility, then initialize the default Wine environment for running Windows applications.
SETUP sudo zyphor setup theme light Apply the Windows-10 inspired desktop theme for a bright and familiar user experience.
SETUP sudo zyphor setup theme dark Apply the Kali-Dark inspired desktop theme optimized for developers and low-light environments.
SETUP sudo zyphor setup web-server Sets up an Apache web server by enabling required modules, configuring SSL, creating a VirtualHost, setting the site document root, and enabling and restarting the Apache service.
PACKAGE sudo zyphor pkg install <pkg> Install software packages from configured repositories while automatically resolving required dependencies.
PACKAGE sudo zyphor pkg remove <pkg> Uninstall a package and optionally remove associated dependencies that are no longer required.
PACKAGE sudo zyphor pkg search <key> Search available repositories for packages matching a keyword, name, or partial package identifier.
PACKAGE sudo zyphor pkg list Display all currently installed packages along with their versions and installation status.
SERVICE sudo zyphor service restart <name> Restart a running service to apply configuration changes or recover from operational issues.
SERVICE sudo zyphor service list Lists system services and displays their current running status and whether each service is enabled or disabled at boot.
SERVICE sudo zyphor service start <service> Starts a specified system service using systemd and reports whether the service started successfully.
SERVICE sudo zyphor service status <service> Displays the current status and detailed information of a specified system service.
SERVICE sudo zyphor service stop <service> Stops a specified system service using systemd and reports whether the service stopped successfully.
NETWORK / STORAGE sudo zyphor smb list Lists the available SMB network shares on a specified IP address using the provided username.
NETWORK / STORAGE sudo zyphor smb disk-list Displays a list of available disks and their partition information on the system.
NETWORK / STORAGE sudo zyphor smb disk-mount Mounts an NTFS disk partition to a named directory under /mnt for access through the filesystem.
NETWORK / STORAGE sudo zyphor smb mount Connect and mount a remote SMB/CIFS network share, making it accessible like a local directory.
NETWORK / STORAGE sudo zyphor smb share-add Share a local folder over SMB so it's accessible from other devices, including Windows PCs, on the network.
NETWORK / STORAGE sudo zyphor smb share-list List all folders currently being shared over SMB from this machine.
NETWORK / STORAGE sudo zyphor smb share-remove Stop sharing a folder that was previously shared over SMB.
FTP sudo zyphor ftp upload Transfer files securely from the local system to a configured FTP server.
FTP sudo zyphor ftp download Downloads a file from an FTP server by prompting for the FTP host, username, remote file, and optional local save path.
FTP sudo zyphor ftp list Lists the files and directories available on an FTP server by prompting for the FTP host and username.
SSH sudo zyphor ssh connect Establish a secure encrypted shell session to a remote server for administration and maintenance.
SSH sudo zyphor ssh cmd Execute commands on a remote server over SSH without opening an interactive terminal session.
DOCTOR sudo zyphor doctor scan Analyze the system for configuration issues, missing dependencies, broken packages, and common problems.
DOCTOR sudo zyphor doctor fix Attempt to automatically repair issues detected during a diagnostic scan.
DOCTOR sudo zyphor doctor report Generate a comprehensive diagnostic report for troubleshooting and technical support purposes.
BUILD sudo zyphor build package [dir] Build a Debian package from a project directory, simplifying software packaging and distribution.
BUILD sudo zyphor build repo Generate repository metadata files such as Packages.gz for hosting a Debian-compatible package repository.
CORE sudo zyphor refresh Refreshes the Zyphor OS system by resetting first-boot defaults and rebooting the system to apply them.
CORE sudo zyphor help Display the complete Zyphor CLI command reference, categories, usage examples, and available options.

Zyphor Command Center

Installation: zyphor pkg install zyphor-comand-center

Zyphor Command Center — A graphical management interface built on top of Zyphor CLI, providing an intuitive point-and-click experience for non-technical users. Perform system updates, install software, manage services, configure development environments, mount network shares, run diagnostics, and customize system settings without memorizing terminal commands.

ZyLearn

Installation: zyphor pkg install zylearn

ZyLearn is an interactive learning tool that teaches Linux through practical, hands-on experience. Instead of relying solely on documentation or videos, ZyLearn gives you guided lessons, challenges you complete on your own system, and automatic checks that tell you whether you got them right.

ZyLearn also includes an optional learning skeleton: zylearn setup skeleton downloads the zyphor-os-minimal project into the current directory, together with a GUIDE.md file containing step-by-step instructions for Linux operating system development.

ZyLearn serves as a hands-on educational environment for students, Linux enthusiasts, and aspiring distribution maintainers who want to understand how modern Linux distributions work and are built from the ground up.

Getting Started

zylearn doctor             # check that your system is ready
zylearn lesson list        # see all lessons
zylearn lesson show 01-filesystem
                           # read a lesson and try its commands
zylearn check 01-filesystem
                           # verify your challenge automatically
zylearn progress           # see how far you have come

Available Commands

Command Description
zylearn lesson list List all lessons. Lessons you have completed are marked with [x].
zylearn lesson show <name> Read a lesson. Each lesson explains a topic, gives you commands to try, and ends with a challenge.
zylearn check <name> Automatically verify your work for a lesson. ZyLearn reports each requirement as [ ok ] or [FAIL] with a hint explaining how to fix it. When every check passes, the lesson is marked as completed automatically.
zylearn lesson done <name> Manually mark a lesson as completed. Useful for lessons that have no automatic checks.
zylearn progress Show a progress bar with the number of lessons you have completed.
zylearn setup skeleton Install the Zyphor OS learning skeleton environment in the current directory. This command downloads the zyphor-os-minimal project, including the GUIDE.md documentation that walks learners through Linux distribution development step by step. Requires git and an internet connection.
zylearn doctor Check that your system is ready: shows the current user and verifies that git is installed, the lessons are found, and your progress can be saved. Failed checks include the command to fix them.
zylearn show logs Display your command history: every ZyLearn command you ran, with a date and time.
zylearn clear logs Delete your command history. Your lesson progress is kept; it is stored separately.
zylearn --help (or -h) Display command usage information, available commands, and options.
zylearn --version (or -v) Show the installed ZyLearn version.

Lessons

Lesson What you learn
01-filesystem How the single Linux directory tree is organized, and how to move around it and create folders and files.
02-permissions Reading file permissions, and using chmod to control who can read, write, and run a file.
03-processes Listing, monitoring, and stopping running programs.
04-pipes Redirecting output to files and connecting commands together with pipes.
05-packages Searching for, installing, and removing software with apt.

How Checks Work

Automatic checks only look at the result of your work, for example whether a file exists, has the right permissions, or contains the expected text. They never run commands on your system, so running zylearn check is always safe.

Where ZyLearn Stores Data

  • Your command history and lesson progress are stored per user in ~/.local/state/zylearn/, and no other user can read them.
  • The lessons themselves are plain text files installed in /usr/share/zylearn/lessons/.
  • git is installed automatically as a dependency, and is only used by zylearn setup skeleton.

ZyWin

Installation: zyphor pkg install zywin

ZyWin is a lightweight command-line utility that makes running Windows software on Zyphor OS easier. It automatically detects supported installer formats, prepares the required Wine environment, and launches applications with minimal user interaction.

ZyWin supports Windows executable files (.exe), Windows Installer packages (.msi), and optical disc images (.iso). When an ISO image is provided, ZyWin automatically extracts its contents to a temporary directory, searches for executable installers, and prompts the user to select one when multiple executables are available.

Each application is executed using its own dedicated Wine prefix stored under ~/.local/share/zywin/prefixes/. This keeps applications isolated from one another, helping prevent registry conflicts, DLL incompatibilities, and configuration issues that can occur when sharing a single Wine prefix.

Temporary files created while extracting ISO images are stored under /tmp/zywin-installer-iso-extract-<timestamp>. These can be removed at any time using the cleanup command.

Available Commands

Command Description
zywin <application.exe> Launches a Windows executable using a dedicated Wine prefix.
zywin <installer.msi> Installs an MSI package using Wine's Windows Installer service.
zywin <image.iso> Extracts the ISO, locates executable installers, and launches the selected executable using Wine.
zywin cleanup Removes temporary ISO extraction directories created by ZyWin.

ZyWin UI

Installation: zyphor pkg install zywin-ui

ZyWin UI — A graphical interface for installing and initializing Windows applications on Zyphor OS using Wine, providing a simple point-and-click experience without requiring terminal commands.

Zyphor Updates

Installation: zyphor pkg install zyphor-updates

Zyphor Updates is the official post-installation package for Zyphor OS. It provides a curated collection of software, developer tools, desktop enhancements, system utilities, multimedia applications, and Zyphor-specific components that extend the base operating system experience.

Zysh

Installation: zyphor pkg install zysh

Zysh is the official Zsh customization layer for Zyphor OS. It enhances the standard Zsh shell with Zyphor-specific branding, version information, color schemes, and terminal experience improvements. Rather than replacing Zsh, Zysh operates on top of it, extending and customizing the shell to provide a consistent and recognizable command-line environment across the Zyphor OS ecosystem.

Zyphor Smart Downloads

Installation: zyphor pkg install zyphor-smart-downloads

Zyphor Smart Downloads is a lightweight background utility that keeps your Downloads folder clean. It automatically sorts finished downloads into each user's own folders, so images, music, videos, and documents end up where they belong without any manual work.

Files are sorted by type: images are moved to ~/Pictures, music to ~/Music, videos to ~/Videos, PDF files to ~/Documents/PDFs, office documents, text files, and ebooks to ~/Documents, and archives to ~/Documents/Archives. Installers such as .deb, .iso, and AppImage files are grouped under ~/Downloads/Software. Folder locations follow the user's xdg-user-dirs settings, so translated folder names are supported.

A file is never moved while it is still being downloaded. Files with partial extensions such as .part, .crdownload, or .aria2, files that were modified recently, files whose size is still changing, and files currently open in a running program (for example a video that is playing) are skipped and checked again on the next scan.

Before a file is moved, it is checked for damage. Truncated images and PDFs, corrupt archives, empty files, and web pages saved with a wrong extension are detected and moved to ~/Downloads/Damaged instead of your real folders.

After moving, each file is renamed using the format <date-with-seconds>-<filename>, for example 20261022-143005-photo.jpg. If a file with the same name already exists, a counter is added automatically so nothing is overwritten.

The scan interval is fully configurable, from as little as 5 seconds up to hours. Settings are stored in /etc/zyphor-smart-downloads/zyphor-smart-downloads.conf, and each user can override them in ~/.config/zyphor-smart-downloads.conf. Activity is recorded in ~/.local/state/zyphor-smart-downloads/organizer.log, which is rotated automatically when it grows past 1 MB.

Available Commands

Command Description
zyphor-smart-downloads status Shows the current settings, whether the cron entry is installed, and the time of the last scan.
zyphor-smart-downloads run Organizes your Downloads folder immediately, without waiting for the next scheduled scan.
zyphor-smart-downloads log Displays your recent activity log, including moved and quarantined files.
sudo zyphor-smart-downloads set-interval <time> Changes how often files are organized. Accepts seconds, minutes, or hours, for example 15s, 30s, 5m, or 1h.
sudo zyphor-smart-downloads set <KEY> <VALUE> Changes any setting from the table below.
sudo zyphor-smart-downloads enable / disable Turns automatic organizing on or off without uninstalling the package.

Configuration Options

Option Description
SCAN_INTERVAL How often the Downloads folder is scanned. Default: 1m. Minimum: 5s.
MIN_FILE_AGE How long a file must stay unmodified before it can be moved. Default: 10s.
STABILITY_WAIT Delay between two file size checks used to detect a download that is still growing. Default: 2s.
DATE_SOURCE Source of the date in the new filename: birth (default), mtime, or now.
DATE_FORMAT Format of the filename date prefix. Default: %Y%m%d-%H%M%S.
INCLUDE_USERS / EXCLUDE_USERS Limits organizing to specific users, or skips specific users. By default every normal user is included.
UNKNOWN_FILES leave (default) keeps unrecognized files in place, misc moves them to ~/Downloads/Other.
DAMAGED_ACTION quarantine (default) moves damaged files to ~/Downloads/Damaged, leave keeps them in place.

Contributing


Contibuting to Packages

Zyphor OS maintains its own collection of official packages that are developed specifically for the distribution. These packages include system utilities, desktop enhancements, command-line tools, themes, configuration packages, applications, and other components that make up the Zyphor OS experience.

  1. zyphor-cli - shell script
  2. zyphor-command-center - python
  3. zyphor-command-center-web - php
  4. zylearn - C
  5. zyphor-updates - Debian config file
  6. zysh - shell script
  7. zyshell - C (removed temporary)
  8. fastfetch-config-1 - filesystem config and Debian config file
  9. grub-screensaver-1 - filesystem config and Debian config file
  10. zyphor-display-mac-v1 - filesystem config and Debian config file (optional - for v1 Stable)
  11. zyphor-os-release - filsystem config and Debian config file
  12. zyphor-repo-config - filsystem config and Debian config file
  13. zyphor-whats-new - filsystem config, html and Debian config file
  14. zyphor-wallpapers-default-2026-2027 - filsystem config, images and Debian config file
  15. zyphor-wallpapers-nature - filsystem config, images and Debian config file
  16. zyphor-wallpapers-pragmata - filsystem config, images and Debian config file
How to Contribute?

Want to help improve Zyphor OS? Awesome! You can contribute by updating existing packages, creating new ones, fixing bugs, improving the documentation, or adding new features.

  • Step 1: Fork the https://github.com/zyphor-os/zyphor-os-desktop repository.
  • Step 2: Clone your fork:
    git clone https://github.com/YOUR_USERNAME/zyphor-os-desktop
  • Step 3: Open the /pkg folder.
  • Step 4: Find the package you want to update, or create a new one.
  • Step 5: Make your changes and test them.
  • Step 6: Commit your changes and push them to your GitHub fork.
  • Step 7: Open a Pull Request so the Zyphor OS maintainers can review your work.
How to Test a Package?

The easiest way to test a package is by installing zyphor-cli. It comes with a command that builds packages for you:
zyphor build package PACKAGE_NAME

For example, if you're updating the zylearn package in Ada Lovelace LTS:

  1. cd pkg/v2/zylearn
  2. Update the version number in DEBIAN/control.
  3. Edit the files you want to change.
  4. Go back to the package directory:
    cd ..
  5. Build the package:
    zyphor build package zylearn
  6. A .deb file will be created, ready for testing.

💡 Always test your package in a virtual machine or another safe environment before installing it on your main system.

Creator

A Message from the Creator

Mark Jason Penote Espelita
Full Stack Web Developer | Lead OS Maintainer

To everyone who has been part of the development of Zyphor OS—the contributors, the creators of the technologies we rely on, and the entire open-source community—thank you so much for your support and dedication.

Let's continue working together to make Linux easier to use and more accessible for everyone.

Thank you for supporting Zyphor OS and being part of this journey.

The Technology Stack Behind Zyphor OS