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
| 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
~/zylearn-practice/, so you can experiment freely without touching your real files.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/. gitis installed automatically as a dependency, and is only used byzylearn setup skeleton.
ZyWin
Installation: zyphor pkg install zywin
zyphor setup wine first to install and configure Wine before using 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
cron
service must be running. It is enabled and started automatically during installation.
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.
zyphor-cli- shell scriptzyphor-command-center- pythonzyphor-command-center-web- phpzylearn- Czyphor-updates- Debian config filezysh- shell scriptzyshell- C (removed temporary)fastfetch-config-1- filesystem config and Debian config filegrub-screensaver-1- filesystem config and Debian config filezyphor-display-mac-v1- filesystem config and Debian config file (optional - for v1 Stable)zyphor-os-release- filsystem config and Debian config filezyphor-repo-config- filsystem config and Debian config filezyphor-whats-new- filsystem config, html and Debian config filezyphor-wallpapers-default-2026-2027- filsystem config, images and Debian config filezyphor-wallpapers-nature- filsystem config, images and Debian config filezyphor-wallpapers-pragmata- filsystem config, images and Debian config file
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-desktoprepository. - Step 2: Clone your fork:
git clone https://github.com/YOUR_USERNAME/zyphor-os-desktop - Step 3: Open the
/pkgfolder. - 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.
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:
cd pkg/v2/zylearn- Update the version number in
DEBIAN/control. - Edit the files you want to change.
- Go back to the package directory:
cd .. - Build the package:
zyphor build package zylearn - A
.debfile 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.
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