mihawk-99/PS5_MihawkOS

Windows programs on a PlayStation 5, started from a desktop of their own.
A homebrew title for consoles that already run homebrew: a Wine runtime underneath, and Mihawk OS, a
Windows‑style desktop with a taskbar, Start, File Explorer and a web browser, on top.

Status · Requirements · Set up · Add programs · Controls · Troubleshooting · Build · Credits

_{PPSA99170 · firmware 10.01 · 64-bit and 32-bit Windows programs · in development · status of 2026-10-19}

MihawkOS is two things that ship together:

• A runtime. Wine with Proton's components (DXVK and VKD3D-Proton for Direct3D, Mesa's Zink for OpenGL), pinned from GE-Proton 11-7 and patched so its Unix side runs on the console. Each Windows program runs in a process of its own; the title owns the shared Wine server, the GPU broker that draws for every program, the display, the controller and the sound mixer.
• A desktop. Mihawk OS is a Windows 11-style desktop, built from Microsoft's published design numbers, with no proprietary Microsoft code, fonts, icons or artwork; the open-source Microsoft assets it uses are listed under Credits. Its wallpaper, Aero Meadow, its music and its mark are the project's own.

You open MihawkOS from the PS5 home screen (the first time, a short guided setup comes first), choose Mihawk OS, and start a program from its desktop shortcut, as on a PC. A full-screen game takes the screen directly (Game Mode) and the desktop comes back when it ends.

MihawkOS runs on the console today, built and installed from a Linux PC. Every claim below is something the console showed; it is not a compatibility list, and each program needs its own evidence. The proof behind each line, and its limits, are in docs/FEATURES.md and docs/PLAN.md.

What the console has shown

Built and host-tested, not yet fully shown on the console: the guided first launch (its screens were walked once on the console, in Japanese, up to Preparing with a simulated install; the nine languages and the music are host-tested only), installing the runtime from a USB stick or over HTTPS with no PC, the title setting itself up on its first start, and signed self-updates.

Not yet, or out of scope: a prebuilt release (you build MihawkOS yourself today), kernel drivers and anti-cheat, rumble, moving the desktop focus with the D‑pad, and any console but a PS5 Pro on firmware 10.01.

The last full console battery, gate-2026-10-18-item3-01 (2026-10-18, commit 3cbc744), passed 86 of 86. Commits after 3cbc744 were made, at the owner's instruction, after host tests and a production build but without a console battery; each one says so.

• A PS5 Pro on firmware 10.01. It is the only console MihawkOS has run on. A standard PS5, a Slim and any other firmware are untested. The setup tool stops once the console reports another firmware.
• A console that already runs homebrew, with the payloads under Payloads loaded on every boot, and your own copy of ShadowMountPlus to mount the title. You set these up yourself, with tools from their own authors. This project does not provide, link to or explain a jailbreak, and whether you may modify your console is yours to check where you live (LEGAL.md).
• An x86_64 Linux PC on the same network with the host tools. It builds MihawkOS and installs it over FTP.
• Your own programs and games, as Windows folders you own. This repository never contains, fetches or shares game data, keys or firmware.
• Space on /data. The runtime and the tools' check prefix take about 2.2 GiB (the runtime about 1.45 GiB, the check prefix about 0.75 GiB); the Mihawk OS prefix adds about 1.3 GiB once used, before any game.
• Time and space on the PC. A first build downloads well over 1 GB and builds Wine for hours.

The owner builds on CachyOS (Arch Linux). Other distributions are untested; the names below are the upstream projects, so look up your distribution's package for each.

• clang, clang++, lld and LLVM 23.1.1 (llvm-ar, llvm-ranlib, llvm-objcopy, llvm-config). The version matters: the Lapy daemon the title ships is pinned by SHA-256, and another compiler version gives another file. The payload SDK finds LLVM through llvm-config: LLVM_CONFIG if set, else llvm-config-21 down to -15, else plain llvm-config. If your system has one of those numbered ones, set LLVM_CONFIG to the 23.1.1 one.
• Build tools: git, curl, wget, unzip, tar, xz, zstd, patch, make, cmake, ninja, meson, pkg-config, autoconf, bison, flex, perl, glslang (glslangValidator), a C compiler named cc (or one named in CC), the zlib headers and the FreeType development files.
• Python 3.12 or later with Pillow, pefile, fontTools, numpy, mako, MarkupSafe, PyYAML, packaging and cryptography.
• ImageMagick 7.1.2-32 Q16-HDRI with librsvg, for the Mihawk OS icons. tools/fetch-all.sh unpacks Arch Linux's package of that release into .deps/ on Arch-based hosts; elsewhere, put a build of that exact release with librsvg on PATH.
• Not needed on the system: the Windows cross compiler and Wine; tools/fetch-all.sh puts the pinned ones in .deps/.

What the tested console runs alongside MihawkOS. This repository ships none of them; each comes from its own project.

On every boot, in this order:

1. Your console's homebrew enabler. The tested console uses kstuff alone; etaHEN is not needed.
2. elfldr, then websrv (port 8080). Keep elfldr resident while you play: the title starts its /data access service and every Windows helper through it.
3. ftpsrv (port 2121). The PC tools copy the title, the runtime and your programs over FTP.
4. klogsrv (port 3232). The setup tool watches the kernel log for storage errors, and stops if the log is gone.
5. Check that ShadowMountPlus is running. It mounts /data/homebrew/PPSA99170 so the title starts from the home screen.

Started for you; never start them yourself: ps5vkctl (port 9111), the control service the PC tools talk to, which the setup tool sends when nothing answers; and the Lapy daemon, which the title starts to reach /data. Two copies of either must never run.

MihawkOS does not ship, patch or install ShadowMountPlus. Known limitation: with stock 1.7beta4 on 10.01, other homebrew may not start after MihawkOS closes (docs/LAUNCH_AFTER_EXIT.md); restart the console to recover.

What still stands between a fresh clone and a working console, as of 2026-10-19:

• The Lapy daemon needs exactly clang and LLD 23.1.1 to rebuild. A clean room built fresh clones of 5c5728e and 33c587a through the whole production build (2026-10-19; fetch 788 s, build 1922 s), after three build gaps were fixed: the licence staging order, stripping only PE images, and extracting DXVK and VKD3D-Proton. Its one open gap is the daemon: tools/build-production.sh refuses any other compiler version, current CachyOS ships 23.1.3, so the clean room used the pinned ELF (c9710b7a). Every production build since 2026-10-16 carries that daemon, and the later console batteries, which need /data, passed with it; no record names it starting.
• ImageMagick outside Arch-based hosts: no pinned build with librsvg runs there yet.
• The setup tool's own Mihawk OS prefix session (S9) has never run, and no apply run has yet ended ready.

Steps 0 to 6 are done once. After that, see Every time you play.

Clone these next to each other. The build reads PS5_Mesa, PS5_PayloadSDK and PS5-Lapy-JB-Daemon at their pinned revisions with git archive, so a plain clone of each default branch is enough for them. PS5_Vulkan is the exception: its working tree must stay at its pin, because the PC tools import its tools/.

<any folder>/
├── PS5_MihawkOS/         this repository
├── PS5_Vulkan/           RADV's link recipe and the console tools; holds .env (step 4)   pin f410e67
├── PS5_Mesa/             Mesa, for RADV and Zink                                       pins 1ba9874, b3588f7
├── PS5_PayloadSDK/       the payload SDK fork                                          pins 611893f, b83202b
└── PS5-Lapy-JB-Daemon/   the /data access daemon                                       pin 5b8397b

git clone https://github.com/mihawk-99/PS5_MihawkOS.git
git clone https://github.com/mihawk-99/PS5_Vulkan.git
git clone https://github.com/mihawk-99/PS5_Mesa.git
git clone https://github.com/mihawk-99/PS5_PayloadSDK.git
git clone https://github.com/mpereiraesaa/PS5-Lapy-JB-Daemon.git

PS5_VKHomebrewUI (the launcher's UI kit) is read from beside them too, or fetched from GitHub when it is missing.

PS5_Vulkan's own setup. The build copies two files PS5_Vulkan builds, runtime/libc.prx and build/host/ps5-native-tool, so build them at the pin:

cd PS5_Vulkan
git checkout f410e67a0241b3e8edcdbcd2a9b285dfc4a412ed
bash tools/setup-native-dependencies.sh
make                                      # stops at its own demo app (ps5_fp_ieee); MihawkOS does not use it
ls runtime/libc.prx build/host/ps5-native-tool
cd ../PS5_MihawkOS

The pinned one-time inputs:

bash tools/fetch-all.sh            # downloads, the PRX tool, the Lapy daemon, the host Wine build (hours)
bash tools/fetch-all.sh --check    # changes nothing: each pin's SHA-256 and a HEAD request to each URL

It fetches llvm-mingw, the DXVK sources, GE-Proton11-7, the OpenGL SDK, the payload SDK v0.40 and ImageMagick 7.1.2-32, each checked by SHA-256, then builds the PRX converter, the Lapy daemon, the Wine sources at their pins and the host Wine build. Running it again skips what is there. PS5_PROTON_CACHE=/path/to/folder reuses files you downloaded before when their name and SHA-256 match. tools/build-production.sh fetches the remaining pins itself, so the build needs the network too.

• Power Saving: never enter rest mode. Rest mode unloads the payloads, and the tools then need a real restart.
• Automatic system updates: off.
• Clock: correct. Secure HTTPS from Windows programs checks certificates against it.

In the order under Payloads, then check that ShadowMountPlus is running.

bash tools/build-production.sh --jobs 8

This builds the title into dist/PPSA99170/ and stages the Wine runtime in .deps/staged/.

Copy ../PS5_Vulkan/.env.example to ../PS5_Vulkan/.env and set PS5_HOST to the console's address:

PS5_HOST=<the console's address>
FTP_PORT=2121

The file is git-ignored, and the tools mask the address in what they print. Mask it yourself before pasting anything.

Close MihawkOS first: the tool never force-closes a title.

python3 tools/console-setup.py --check   # read only: 0 ready, 2 something to do, 1 blocked
python3 tools/console-setup.py           # apply: 0 ready, 1 stopped

It reads the console's state first and does only what is missing, so running it again resumes where it stopped. It never deletes anything on the console and never launches a game. When the Mihawk OS prefix is missing, it opens one Mihawk OS session of its own (a 150 s budget; below).

Choose MihawkOS on the home screen. The first open shows the guided setup: choose a language; with the runtime already installed it says so, then Continue and Done (or Skip setup on Welcome). After that, choose Mihawk OS in the launcher. A title folder that did not exist before needs up to about 45 s before ShadowMountPlus lets it start; a refusal in that window is not a crash.

1. Cold-boot the console. Never use rest mode.
2. Load the payloads, in the order under Payloads.
3. Only after a real restart, and only if you will use the PC tools: run python3 tools/console_guard.py new-boot on the PC once the payloads are loaded. It saves the boot's kernel log and checks it for storage damage; until it has run, the PC tools refuse to write or launch. Opening MihawkOS from the home screen does not need it.
4. Open MihawkOS.

Reinstall the same 10.01 image and redo step 1, then the every-boot routine. If the console's address changed, fix PS5_HOST in ../PS5_Vulkan/.env. The setup tool then rebuilds the title, the runtime and both prefixes. Your Windows programs, saves and settings were on /data and are gone: copy them again from your own copies.

• You put: your program folders in ps5proton/prefixes/mihawk/drive_c/Games/, an optional games/<id>/game.json per program, and optionally an empty library-show-all.
• The setup tool puts: the title, dev.conf, the runtime, run/ and the tools' check prefix.
• MihawkOS writes: the Mihawk OS prefix, logs, caches and your settings.

/data
├── homebrew/
│   ├── dev.conf                        two lines for the Lapy daemon
│   └── PPSA99170/                      the MihawkOS title
└── ps5proton/
    ├── runtime/ge11-7/                 the Wine runtime and its deploy-manifest.json
    ├── run/proton-payload-child.elf    the loader every Windows helper starts from
    ├── prefixes/
    │   ├── mihawk/                     Mihawk OS: the desktop and every program
    │   │   └── drive_c/Games/<Name>/   your Windows programs, C:\Games\<Name>
    │   └── probe/                      a separate prefix the tools use for checks
    ├── games/<id>/game.json            the library, one entry per program
    ├── logs/                           every log the title and Wine write
    ├── caches/                         shader caches
    ├── controls.txt                    mouse-button choices
    └── game-mode.txt                   Game Mode on or off

C: in Mihawk OS is prefixes/mihawk/drive_c, and Z: is the console's root, so /data/... is also Z:\data\....

A prefix is one Windows installation: a registry, a C: drive and its user folders. Mihawk OS and every program share one, prefixes/mihawk. The PC never sends it; the console builds it the first time Mihawk OS opens, or the setup tool's S9 step does it for you.

By hand: open MihawkOS (finish or skip the guided setup the first time; when the prefix is missing, its Preparing step runs this first session itself and ends it), choose Mihawk OS, give the first session time (the tools' own fresh-prefix check takes about 150 s), then Start → End session. Do not open a game in this first session: a game started in a brand-new prefix's first session never got the DualSense; in later sessions it did. The cause is still open.

Check it: python3 tools/console-setup.py --check shows S9 prefix: done. Later launches keep the prefix and repair any missing or outdated baseline file; your registry, settings and saves are never replaced.

The launcher shows Mihawk OS. Your programs open from shortcuts on its desktop, which the title writes at the start of each session for every folder in C:\Games with one program at its top, and every library entry in its prefix. Your own shortcuts are never touched.

The quick way: copy the folder. Put the program's folder in /data/ps5proton/prefixes/mihawk/drive_c/Games/<Name> (C:\Games\<Name>) over FTP on port 2121. If the folder holds one x86-64 or 32-bit .exe at its top (uninstallers named unins* and Unity's crash handler are not counted), the next Mihawk OS session puts a shortcut named after the folder on the desktop.

With an entry. A folder whose program is in a subfolder, one with several programs at its top, or a program that needs arguments or settings needs an entry, game.json. Its line in logs/title-last.log (games folder <Name>: ...) says which.

{
  "name": "My Program",
  "detail": "Second line in the library",
  "executable": "C:\\Games\\MyProgram\\MyProgram.exe",
  "directory": "C:\\Games\\MyProgram",
  "prefix": "mihawk"
}

Send the folder and its entry together, resumably and with every file read back:

python3 tools/deploy-folder.py --source /path/to/MyProgram --folder MyProgram \
    --id myprogram --game-json myprogram.json

--dry-run previews; --folder and --id take only letters, digits, - and _. An entry with a problem gets no desktop shortcut, and its reason is in logs/title-last.log (game <id> (<name>): <reason>). Only x86 programs are accepted, 64-bit or 32-bit; a 32-bit one runs through WoW64.

Controls assigns the left, right and middle mouse clicks to a DualSense button: the touchpad, Cross, Circle, Square, Triangle, L1, R1, L2, R2, L3, R3, a D-pad direction or Options. The default is left click on the touchpad click; Restore defaults brings it back. Choices apply to every program.

Game Mode is on by default and applies from the next launch. A full-screen game's frames then go straight to the screen, and the desktop unloads while it plays and returns when it ends. If a game's screen stays black, turn Game Mode off: every program is then shown inside the desktop.

• Touchpad is a trackpad: move to point, click to left-click, click with two fingers to right-click, hold the click and move to drag.
• USB keyboard and mouse work, through a USB-C hub in the tests; one plugged in later is found within 3 s.
• Start → End session returns to the launcher. Use it rather than the PS button: the registry is saved every 30 s, so a session ended from outside can lose up to 30 s of settings.
• While a game runs, Options goes to the game; there is no hold-to-quit inside a session.

1. Close MihawkOS on the console: End session, then hold Options in the launcher. The tools refuse to write while a title runs.
2. Rebuild: bash tools/build-production.sh.
3. Re-run python3 tools/console-setup.py. It sends only the title files that differ and redeploys the runtime only when its manifest changed. Existing prefixes are kept.

Logs are in /data/ps5proton/logs/: title-last.log (the title, written every 2 s), wine-last.log and wine-stdout.txt (Wine and the first program's output), sessions/0, 1, 2 (the last three sessions, with each helper's wine-child-<pid>.log) and lapy-service.log (the /data access service). Mask the console's address before you paste a log anywhere.

For developers. Read AGENTS.md first: the rules, the commit gate and the sibling repositories the build expects (step 0).

bash tools/fetch-all.sh                         # once: the pinned one-time inputs (hours: host Wine)
bash tools/build-production.sh --jobs 8         # runtimes, title, Mesa, DXVK; staged runtime
bash tools/host-tests.sh                        # host tests (some read the build's .deps/ outputs)
python3 tools/console-setup.py                  # deploy and read back
python3 tools/gate.py run --name <unique-run>   # the console test battery, before a code commit
python3 tools/publication-check.py all          # safe to publish: no addresses, secrets, game data or game names

The hooks (git config core.hooksPath tools/git-hooks) refuse a code commit that the console battery did not pass on exactly that build, and run the privacy guard (tools/privacy_check.py) on every commit.

Where to read next: docs/ARCHITECTURE.md (who owns what, how a program starts), docs/PLAN.md (what is being built and what is proven), docs/WINDOWS_PROCESSES.md (Windows programs as payload processes), docs/MIHAWK_OS.md (the desktop session), docs/MIHAWK_BROWSER.md (the browser), docs/SELF_INSTALL.md (installing without a PC) and docs/FEATURES.md (accomplishments and their proof limits).

MihawkOS stands on other people's work. Every upstream is pinned by revision or hash, keeps its own licence, and ships its licence text beside the binaries (the runtime's share/licenses/, the title's licenses/). The full list, with every pin, is NOTICE.md; where the platform knowledge came from is docs/PROVENANCE.md.

MihawkOS itself is free software under the GNU General Public License v3.0 or later (LICENSE, LICENSING.md); the few files that keep another licence are named there. Patches to an upstream project keep that project's licence: the Wine patch series is LGPL-2.1-or-later, like Wine. A binary release comes with its corresponding source: this repository at the same revision, its patch series and the pins that rebuild every input.

MihawkOS is an independent hobby project. It is not affiliated with, sponsored by or endorsed by Sony Interactive Entertainment, Microsoft, Valve or any game publisher. PlayStation, PS5 and DualSense are trademarks of Sony Interactive Entertainment Inc.; Windows is a trademark of Microsoft Corporation; Proton is a trademark of Valve Corporation. Other names belong to their owners and are used only to say what the project runs on and is compatible with.

Mihawk OS is not Windows: it contains no proprietary Microsoft code, fonts, icons, wallpapers or sounds, and no Windows logo; the open-source Microsoft assets it uses are credited above. Its look follows Windows 11 from public references. This repository and every build of it contain no game files, saves, keys, firmware or exploits. You are responsible for having the right to the programs you run, and for whether modifying your console is lawful where you live. The full notes are in LEGAL.md.