Ren'Py Web Player

A local Docker-powered browser launcher for Ren'Py games.

Drop in a Ren'Py ZIP, project folder, or prebuilt web build and play it from your desktop browser or Android device on the same Wi-Fi network.

Quick Start | Mobile Setup | Verified Status | Technical Overview

---

Alpha Release Status

This is an alpha test release. The main flow works in the verified environment below, but this is still early software. Issues may appear on untested operating systems, browsers, devices, Ren'Py versions, codecs, or unusual project structures.

If something breaks, please include your OS, browser, Docker version, Ren'Py version, and copied diagnostics from the app's Tools page.

---

What This Does

Ren'Py Web Player runs a local Python server inside Docker and gives you a browser UI for launching Ren'Py games.

Capability	Status
Launch Ren'Py distribution ZIPs	Verified
Launch raw Ren'Py project folders	Verified
Launch prebuilt Ren'Py web builds	Supported compatibility path
Desktop browser play on the host PC	Verified
Android play over local Wi-Fi	Verified on Pixel 9 Pro
Automatic local HTTPS certificate generation	Verified
Mobile setup page with QR/certificate downloads	Verified
Engine, SDK, game, and session caching	Verified
System Check and Cache Manager tools	Verified

---

Quick Start

1. Install Docker

Install Docker Desktop or another Docker-compatible runtime with Docker Compose support.

2. Start the app

Linux

./start-linux.sh

macOS

Double-click start-macos.command, or run:

./start-macos.command

Windows PowerShell

Right-click start-windows.ps1 and choose "Run with PowerShell", or run:

.\start-windows.ps1

3. Open the launcher

On the host PC:

http://localhost:8000

Drop a Ren'Py ZIP/folder onto the launcher, or use Browse ZIP / Browse folder, then click Launch Game.

---

Mobile Setup

Mobile browsers need a trusted HTTPS connection for service workers, Cache Storage, and related browser features. The app automates certificate creation, but Android/iOS still require you to approve trust manually.

Android

1. Start the app on your PC.
2. Open this from your phone on the same Wi-Fi:

http://YOUR_LAN_IP:8000/mobile-setup

3. Download the Android certificate.
4. Install it as a CA certificate in Android Settings.
5. Open:

https://YOUR_LAN_IP:8443

iPhone/iPad

This is not yet tested for the alpha release, but the intended flow is:

1. Open http://YOUR_LAN_IP:8000/mobile-setup.
2. Download the iOS profile.
3. Install the profile in Settings.
4. Enable full trust for the root certificate in Certificate Trust Settings.
5. Open https://YOUR_LAN_IP:8443.

More details: docs/mobile-https.md

---

Verified Status

Tested Environment

Local automated tests and Docker smoke tests were run on:

Component	Tested Value
OS	Nobara Linux 43 KDE
Kernel	7.0.5-200.nobara.fc43.x86_64
Container runtime exposed as docker	Podman 5.8.2
Docker Compose	v2.29.7
Local Python for tests	3.14.4
Docker image base	python:3.12-slim
Node.js	v22.22.2
npm	10.9.7

Manual user testing:

Platform	Result
Host PC through Docker	Works
Pixel 9 Pro Android over local Wi-Fi	Works perfectly
Windows Docker Desktop	Not tested
macOS Docker Desktop	Not tested
iPhone/iPad Safari	Not tested
Desktop Safari	Not tested
ChromeOS	Not tested

Verified Commands

npm test
python3 -m py_compile server.py multipart_parser.py
node --check player.js && node --check sw.js
docker compose config
docker compose build

Docker Smoke-Tested Endpoints

Endpoint	Purpose
GET /health	Runtime status
GET /cache-info	Cache statistics
GET /mobile-setup	Mobile setup page
GET /certs/root-ca.crt	Android/browser certificate download
GET /certs/ios-root-ca.mobileconfig	iOS/iPadOS profile download
HTTPS GET /health on 8443	Secure runtime verification

---

Running Without Helper Scripts

Technical users can run Compose directly:

docker compose up --build

For mobile support, include your LAN IP in the generated certificate:

RENPY_CERT_HOSTS=localhost,127.0.0.1,::1,192.168.1.20 docker compose up --build

Replace 192.168.1.20 with your host PC's LAN IP.

Stop the app:

docker compose down

Remove the app plus cached engines, cached games, sessions, and generated certificates:

docker compose down -v

If you remove the volume, phones/tablets must trust the newly generated certificate again.

---

Technical Overview

Launch paths

• Raw ZIP: uploaded to /prepare-session.
• Raw folder: packed in-browser into an uncompressed TAR and uploaded to /prepare-session-folder-archive.
• Multipart folder fallback: uploaded to /prepare-session-web.
• Prebuilt web build: compatibility path using the service worker.

Server packaging and caching

For raw projects, the server:

1. Detects the Ren'Py version from project files when possible.
2. Downloads the matching Ren'Py SDK/web engine on first use.
3. Extracts and packages the game for web launch.
4. Moves large video files outside the startup ZIP when appropriate.
5. Stores packaged output in a content-addressed cache.

Launch sessions are short-lived pages under:

/sessions/<session-id>/index.html

Those pages point at stable cacheable URLs:

/engines/<renpy-version>/...
/games/<sha>/game.zip

That stable URL design is why repeat launches are faster.

Docker data layout

Persistent Docker volume: renpyplayer-cache

/data/cache/builds
/data/cache/builds/_games
/data/cache/sdks
/data/cache/web-engines
/data/cache/sessions
/data/certs

The generated local root CA and server certificates live under /data/certs.

Useful endpoints

Endpoint	Description
GET /health	Runtime status and cache paths
GET /cache-info	Cache sizes and file counts
POST /cache-clear	Selective cache cleanup
GET /mobile-setup	Mobile setup page
GET /setup-info.json	Setup URLs and certificate metadata
GET /certs/root-ca.crt	Android/browser certificate download
GET /certs/ios-root-ca.mobileconfig	iOS/iPadOS profile download

More architecture notes: docs/architecture.md

---

Development

Install dependencies:

npm install
python3 -m pip install -r requirements.txt

Run tests:

npm run check:js
npm run test:py
npm test

Run the Python server directly:

python3 server.py

Manual HTTPS mode:

python3 server.py --host 0.0.0.0 --port 8443 --https --cert cert.pem --key key.pem

---

Known Alpha Constraints

• Mobile devices still require manual certificate trust.
• First launch for a Ren'Py version can be slow because the engine/SDK must be downloaded and cached.
• Some prebuilt web builds may behave differently depending on their original build settings.
• Safari/iOS behavior is not verified yet.
• Large game collections and unusual Ren'Py project layouts need more real-world testing.

---

Security Notes

Do not expose this server directly to the public internet. It processes untrusted game archives, downloads Ren'Py SDK assets, and writes cache data to local directories/volumes.

Treat the generated Docker root CA as local-only. Do not publish it, reuse it for unrelated services, or share the Docker cache volume with untrusted users.

See SECURITY.md for more.

---

License

MIT. See LICENSE.