Self-hosting Homegames

Run the game dashboard and shared sessions on one computer. Other devices play through their browsers over your local network. No account is needed.

What you get

The server includes a dashboard, built-in games, a browser client, and session management. You can browse installed games, import portable game ZIPs, join running sessions, or host installed games in a browser tab and invite people to them. This does not install your own copy of this website or Studio.

The launcher supervises homegames-core. Dashboard Play runs the game in a host browser tab, with household room discovery and RTC guests. Keep that tab open and awake. The separate Host with WebSocket option runs game logic in a Node child process or Docker container; that session depends on the server instead.

Download a server bundle

The bundle contains Homegames source, dependencies, Node runtimes, and prefetched game assets. You do not need to install Node, Git, or Docker to launch a supported bundle. This is different from a game page's Download game pack link, which downloads one editable game. Studio and the game player can also download a self-contained HTML copy of a single game.

⤓ Download Homegames ZIP  ·  Windows / macOS / Linux

⤓ Download for macOS

ZIP: extract the entire archive before launching; keep its folders together. On Windows, use Extract All before opening the launcher. macOS 2.0.3 and newer: copy Play Mac.app from the ZIP or disk image to Applications, then open it. The app includes its own server, games and runtimes. Older releases require their surrounding homegames folder and may fail when macOS isolates a newly downloaded app; use 2.0.3 or newer when available.

The current builder does not include Linux ARM or Alpine/musl runtimes. For a Raspberry Pi or another architecture, use a compatible source installation instead of the Linux x64 launcher.

The launcher opens a browser when the server responds. If that does not happen, read its terminal output (Windows/Linux) or use Show Log in the Mac launcher's window, then open the address manually. On Mac, use Stop Homegames when you finish; on Windows/Linux, close the launch window or press Ctrl+C. Closing the browser alone does not stop the server. On a headless source install, use node index.js --no-open to suppress the browser launch.

Run games without Docker defaults to Off. To allow server sessions without Docker, enable it in Server settings on the host computer. Those games run on your machine outside of a sandbox. Docker remains preferred when running. Browser-hosted Play does not require Docker or this setting.

What needs to be available

• A supported computer that stays awake, a writable application-data directory, and browsers able to reach it over the LAN.
• For source installs: Git, Node.js, and npm. The bundle builder currently uses Node 24; use that major version when reproducing its environment. The source repos do not declare one consistent minimum Node version.
• For isolated server sessions: a running Docker daemon using Linux containers. Homegames builds its runner automatically on first use; that first build needs internet access to download the Node base image. Browser-hosted play, including RTC guests, does not need Docker.
• Internet for source dependency installation, optional link discovery, certificate requests, or public RTC signaling. New bundles include built-in game media and local RTC signaling; browsing installed games and playing on the LAN need no internet.

Run from source

Clone Core. The server installs the published client, shared library, Homepad and Squish packages from npm:

mkdir homegames-server
cd homegames-server
git clone https://github.com/homegamesio/homegames-core

cd homegames-core
npm ci

Stop if installation fails. The published client includes its built browser bundle; no separate client build is needed. The current Core dependencies support Squish 1.5.1 (squish-151) and existing 1.5.0 projects (squish-150). Downloaded server releases retain their bundled runtime.

Create homegames-core/config.json with an explicit starting configuration. This avoids inheriting older library defaults:

{
    "HOME_PORT": 7001,
    "HOMENAMES_PORT": 7100,
    "GAME_SERVER_PORT_RANGE_MIN": 7002,
    "GAME_SERVER_PORT_RANGE_MAX": 7099,
    "LINK_ENABLED": false,
    "HTTPS_ENABLED": false,
    "FORK_SESSIONS_ENABLED": false,
    "ERROR_REPORTING": false,
    "MAP_ENABLED": false,
    "TESTS_ENABLED": false,
    "SAVE_FILES_ENABLED": true
}

Docker sessions prepare their runner automatically from the installed runtime. To prepare it in advance from homegames-core, run node docker/prepare-context.js. If you choose to run without Docker, turn on Run games without Docker in Server settings, or set FORK_SESSIONS_ENABLED to true. This permits game code to run on your machine outside of a sandbox.

# From the homegames-core directory:
npm start

This starts Core directly. Stop and restart the process after changing server settings that require a restart. The optional Homegames launcher supervises Core; its dependency pins must match the server release.

Open http://localhost:7001. An existing application-data config or environment variable may override the values above; the server logs report the values in use.

First boot, discovery, and HTTPS

1. Check that the dashboard loads on the server computer.
2. Open the server's LAN IP and main port from another device on the same network.
3. Use Play and join the browser-hosted game from a second device. If using Host with WebSocket, also check that clients can reach the allocated child-session port.

For discovery without HTTPS, set LINK_ENABLED: true in your JSON config and restart. Visit homegames.link from a device using the same public internet connection. The service redirects to your server's LAN IP and port. It does not relay traffic or make that private address accessible from the internet.

Enable secure connections

The dashboard calls this Enable homegames.link under the homegames.link settings. It enables discovery and requests a certificate. Ordinary LAN multiplayer can already work over HTTP; this setting adds the secure hostname path.

1. Choose Enable homegames.link. The server creates a private TLS key and signing request locally. Only the signing request goes to the Homegames API.
2. Wait for Certificate ready. Issuance depends on the API's certificate runner, DNS, and certificate authority; it may take several minutes.
3. Choose Restart to enable homegames.link. The launcher restarts core and opens the link service. This disconnects existing players.

Use the assigned HTTPS hostname, including its port, once TLS is enabled. A certificate for that hostname does not validate localhost or a raw LAN IP. Until the certificate is installed and the server restarted, the link service may show a setup page.

Certificates are stored in hg-certs under application data. The manager checks for renewal daily and attempts renewal within 14 days of expiry. Initial HTTPS activation requires restart; an already-running TLS server can reload a renewed certificate.

If your public IP changes, Homegames prepares a certificate for the new network and asks you to restart when it is ready. Certificate retries retain their request and private key. If Settings reports that operator review is needed, keep the existing certificate files and contact Homegames rather than deleting them to start over.

This release supports one HTTPS server computer per public network. A second computer shows a conflict instead of changing the first server's address. Stop the first server before retrying discovery on the replacement computer.

Local development and offline use

To run core directly after installing its dependencies:

cd homegames-core
npm start

Use the configured HOME_PORT. Direct execution has no launcher to honor the dashboard's restart requests: after core exits to apply settings, start it again yourself.

Set START_PATH to a game's directory or index.js to boot straight into it. Relative paths resolve from the running core package directory. Direct-start games default to START_MODE: "browser": Core serves files to a browser host on the main port, without starting the ordinary dashboard/Homenames stack. Set START_MODE: "server" for Node/WebSocket execution. Restart to load changed code; npm run develop currently references a missing hotload.js, so it is not the source-start command.

New bundles keep game media inside the game folders and use local RTC signaling without external STUN/TURN servers. Choose Play Offline in the Mac launcher, Play Offline Windows.bat, or ./play-offline-linux.sh to override previously saved online settings. From source, run node index.js --offline in the homegames launcher repository. The override lasts for that run and keeps LAN play available over HTTP without changing saved settings.

To add a portable ZIP, open the dashboard on the host computer at its localhost address and choose Import ZIP. The server validates it before saving a separate revision under application data. Imports and saves survive replacing the bundle. In a source checkout, you can also place an unpacked game folder under homegames-core/src/games and restart. Use Import ZIP with a downloaded Mac app so its signed files stay intact. Imported source executes when you play the game.

Configuration and ports

Values resolve in this order: environment variable, user application-data config.json, then the base config found by the running package. If no base file is found, common uses its built-in defaults. Dashboard settings write the user overlay, so those settings survive replacing a downloaded bundle.

Source defaults differ. With no config file, the common library currently supplies main port 9801, Homenames 7400, session ports 8300–8400, and enables both discovery and HTTPS. Use the explicit configuration above for a predictable first run; do not assume a port or TLS mode from a code comment.

Use JSON booleans, such as "LINK_ENABLED": false, not the string "false". Port, page-size, and HTTPS changes need a restart. Run games without Docker takes effect for new sessions immediately. Environment-controlled ports appear read-only in Settings.

Storage, backups, and upgrades

HG_APP_DATA_DIR can override this directory. It contains the user config, certificates, asset cache, and server save data under .save-data. The current dashboard keeps downloaded games under hg-games there. LOCAL_GAME_DIRECTORY can add a separate directory of your own game source; the older DOWNLOADED_GAME_DIRECTORY setting is not consulted by this dashboard path.

Stop the server before backing up or upgrading. Keep application data and any custom game directories; do not publish backups containing private certificate keys. Extract a new bundle separately and launch it after stopping the old one. Your config overrides persist, so a port or setting from an older installation can still apply. Browser-local saves stay with the player's browser, outside this server backup.

Firewall and network access

For the current bundle, LAN clients reach the dashboard on TCP 7001. Node/WebSocket hosting additionally uses TCP 7002–7099. Browser-hosted games instead use RTC between host and guests, with signaling and ICE/STUN/TURN as configured. Use your configured ports if different; loading the dashboard does not verify every game transport.

Server settings, game installation and starting server-side game code are available only from the host computer. LAN guests can browse and play. Keep the Homenames management port on your local network; it is not intended for public internet access.

LAN play needs no internet-facing port forwarding. homegames.link uses an outbound connection and redirects browsers to the LAN address. Guest Wi-Fi, access-point isolation, VPN routing, and networks that share a public IP without sharing LAN connectivity can interfere with discovery or direct connections.

Troubleshooting

Hosting the public services too

Choose services by the features you need. The website, including Studio, is a static site: build it from the homegamesio repository and serve the generated folder from any static host. Projects, saves and exports live in each browser, so there is no account or game database to run.

Automatic invitations and game-copy sharing need a signaling server (the api repository runs one) and may need a TURN relay on some networks. The website reads its signaling address from signalingUrl in site.config.json. Manual pairing with downloaded players can bypass signaling.

Discovery and HTTPS certificates for home servers need the homegames.link service plus the API's certificate service, which uses MongoDB, DNS for your domain and an ACME certificate authority. Start with the service map and each repository's configuration code. There is no single complete-platform installer in the server bundle.

For help, include your installation type, OS, configured ports, and the relevant error without passwords or certificate keys. Email joseph@homegames.io.