PlayWheel turns an installed PS4 collection into a searchable catalogue, personal lists, and a visual randomizer. It runs on your own trusted network, stores its data locally, and never installs permanent software on the console.

[!IMPORTANT] PlayWheel is a companion, not a launcher. Game launching is intentionally disabled in 1.0.0 because the available protocol cannot safely guarantee that another running game will remain open.

Why PlayWheel?

| | Capability | What it gives you | | --- | --- | --- | | 🎡 | Smart randomizer | Filter your library and let the wheel choose the next game. | | 🎮 | Living catalogue | Import installed titles, storage locations, versions, and artwork. | | 💜 | Personal library | Keep favourites, recent picks, notes, lists, themes, and preferences. | | 📡 | Local PS4 status | Discover the console and read its current state over the trusted LAN. | | 📱 | Mobile-first PWA | Use PlayWheel comfortably on phones, tablets, and desktop browsers. | | 🌍 | English + Arabic | Switch languages with full right-to-left support. |

See it in action

How it works

PlayWheel uses the PS4 Title ID as the stable game identity. DDP provides harmless console status without a jailbreak. When you want to import or refresh the catalogue, you can temporarily enable GoldHEN FTP; PlayWheel reads bounded metadata and artwork, then you can disable FTP again.

The browser never connects to FTP, opens SQLite, receives server secrets, or runs host commands.

Quick start

Install PlayWheel from npm without cloning this repository. The wizard offers two production paths: Docker or a direct Node.js systemd service.

Requirements

• a Linux host on the same private network as the PS4
• Node.js 22.13 or newer with npm, which supplies npx
• curl for health and readiness verification
• for Direct Node.js only: systemd, sudo, and standard Linux utilities
• for Docker only: Docker Engine with the Docker Compose plugin
• direct access from the host to the PS4's private LAN address
• persistent storage for the database and imported artwork
• trusted HTTPS for PWA installation, Web Push, and secure cookies outside localhost

Install

npx playwheel@latest

No GitHub account or repository checkout is required on the server. The npm launcher keeps its versioned deployment payload under ~/.local/share/playwheel/package/, checks the selected runtime, previews the exact host changes, installs PlayWheel, and verifies every browser surface before reporting success. Input errors remain in the relevant step, cancellations explain what was left unchanged, and operational commands distinguish a first run from a stopped or unhealthy service.

Choose:

• Docker for an isolated container and named-volume data. Docker also supports the guided local-HTTPS option.
• Direct Node.js for a lighter systemd service. It installs immutable releases under /opt/playwheel, keeps data under /var/lib/playwheel, and automatically restores the previous release if post-install verification fails.

The browser then handles:

1. owner pairing;
2. profile creation;
3. PS4 discovery or private-IP entry;
4. optional GoldHEN FTP setup;
5. storage selection and the first catalogue scan.

Useful host commands:

npx playwheel@latest doctor --runtime node
npx playwheel@latest setup --runtime node --plan
playwheel doctor --runtime node
playwheel status --runtime node
playwheel logs --runtime node
playwheel recover-owner --runtime node
playwheel uninstall --runtime node --plan

Direct Node.js setup installs /usr/local/bin/playwheel, so routine management and full uninstall work from the host without npm or network access. Setup and upgrades still use the signed npm release path. Docker management continues through npx playwheel@latest --runtime docker. Pin a package version when you need reproducible setup automation. For upgrades, backups, reverse proxies, and source-based deployment, use the self-hosting guide.

To retire a host completely, preview and then run the full uninstall:

playwheel uninstall --runtime node --plan
playwheel uninstall --runtime node

For Docker, use npx playwheel@latest uninstall --runtime docker. Uninstall permanently deletes the server database, artwork, accounts, configuration, certificates, backups, runtime, host management command, and local npm payload without creating a backup. It stops PlayWheel first and verifies that its former ports no longer have a listener. It never stops an unrelated process that later claims the same port. Browser/PWA data and client certificate trust must be removed on each device separately; normal file deletion is not secure media erasure. See the full uninstall contract before applying it.

Git is only required for development or a source-based installation.

git clone https://github.com/whoElseButUmar/PlayWheel.git playwheel
cd playwheel
./bin/playwheel setup

The checkout uses the same wizard, but Docker images may be built from source. The manual release contract remains documented for operators with an existing service manager.

Local development

Mock mode exercises the complete browser/server path without contacting a console.

npm ci
npm --prefix www ci
npm run bridge:mock

In a second terminal:

npm run dev

Open http://localhost:5173/playwheel/.

Before submitting a change, run:

npm run typecheck
npm test
npm run build:all

Safety and privacy

• No permanent PS4 changes. PlayWheel runs on a separate host.
• Read-only scanning. The FTP adapter cannot upload, rename, delete, mount, or download game packages.
• Local ownership. SQLite, profiles, scan history, and cached artwork stay in the configured PlayWheel data directory.
• Role-based access. Owner and Administrator accounts control the PS4 and users; Standard accounts receive only the personal library experience.
• Authenticated actions. Sensitive requests require recent passphrase verification, same-origin protections, and—when another Administrator exists—second-person approval.
• Trusted LAN only. Never port-forward GoldHEN FTP or expose PlayWheel's database, secrets, or a host shell.

The full API and threat boundaries are documented in the bridge guide. Please report vulnerabilities according to the security policy, not through a public issue.

Application map

| Route | Purpose | | --- | --- | | / and /hub/ | Local server dashboard | | /playwheel/ | Randomizer | | /playwheel/catalog/ | Installed-game catalogue | | /playwheel/collections/ | Favourites, recent picks, and lists | | /playwheel/profile/ | Profile, preferences, activity, and stats | | /playwheel/sync/ | PS4 setup, storage, scans, and diagnostics | | /playwheel/users/ | Owner/Administrator user management, approvals, and audit history | | /playwheel/docs/ | In-app English documentation | | /playwheel/docs/ar/ | In-app Arabic documentation | | /site/ | Public product site and documentation |

The dashboard and six /playwheel/ application routes are direct static entries; no SPA fallback is required. /site/ and the mounted documentation routes are served from the separately built www/dist/ tree.

Project scope

Version 1.0.10 supports one privately managed PS4 per PlayWheel server, one trusted LAN, and modern Chromium- or Safari-class browsers. Multi-console orchestration, internet accounts, remote cloud control, and package or filesystem mutation are out of scope.

Contributing

Contributions should preserve the browser → PlayWheel server → PS4 boundary and keep changes narrow, testable, and safe for local data. Start with CONTRIBUTING.md, then review the relevant guides:

• Bridge and PS4 integration
• Self-hosting and recovery
• Security policy
• Changelog

License

This repository does not currently include a software license. Until one is added, the default copyright rules apply; please do not assume permission to redistribute or reuse the code.