Self-hosting Homegames

Run a Homegames server on a machine in your house. Everyone on your network gets a game dashboard by typing homegames.link into any browser — no installs on their devices. (Curious how the URL magic works? See how it works.)

What you get

A self-hosted server is one process that does it all: it serves the Homegames client (the thing browsers render games with), runs the dashboard, and spins up game sessions — including the ~50 built-in games and any games you download from the catalog.

With the link service enabled, your server registers itself with homegames.link (an outbound-only connection), and every device on your network reaches it by typing homegames.link. Optionally you can enable HTTPS from the dashboard's settings: your network gets its own *.homegames.link subdomain pointed at the server's LAN address, with a real TLS certificate. Game traffic itself never leaves your network.

Download a build

The quickest way to self-host: a ready-to-run build with nothing to install — no Node, no git, no Docker. One download works on Windows, macOS, and Linux; it carries its own Node runtime for each platform, all the built-in games, and their assets, so it even plays fully offline.

⤓ Download Homegames  ·  Windows / macOS / Linux

Unzip it, then launch:

A browser opens to the dashboard at localhost:7001 when the server is ready, and anyone on your network can join at http://<your computer's IP>:7001. Game sessions run as plain child processes, so Docker isn't needed.

One difference from a source install: homegames.link discovery is off by default in downloaded builds (they're built to run fully offline). To turn it on — so devices on your network can just type homegames.link — create a config file at %APPDATA%\homegames\config.json (Windows), ~/Library/Application Support/homegames/config.json (macOS), or ~/.homegames/config.json (Linux) containing:

{ "LINK_ENABLED": true }

then relaunch. Everything in the zip is readable source — poke around!

Requirements

The downloadable build above only needs the first item below. The rest apply when running from source:

• A machine that stays on while people play — a spare laptop, a Mac mini, a desktop. (Raspberry-Pi-class hardware works for lighter use.)
• Node.js 18 or newer and git.
• Docker — game sessions run in isolated containers. (No Docker? Set FORK_SESSIONS_ENABLED=true to run sessions as plain child processes instead.)
• No sudo and no privileged ports — everything serves on unprivileged ports.
• Internet access for homegames.link discovery, catalog downloads, and (if enabled) certificates. Play itself is LAN-local.

Run from source

Prefer a git checkout — to hack on the server, or to stay on the latest code? The repos reference each other as sibling directories, so clone them side by side into one folder:

mkdir homegames-server && cd homegames-server
git clone https://github.com/homegamesio/squish
git clone https://github.com/homegamesio/homegames-common
git clone https://github.com/homegamesio/homegames-core
git clone https://github.com/homegamesio/homegames-client
git clone https://github.com/homegamesio/homegames

cd homegames-client
npm install && npm run build   # build the browser client bundle (served by the server)

cd ../homegames
npm install                       # links the sibling repos + installs deps
node index.js                     # no sudo needed

A browser opens to the dashboard (localhost:9801) when the server is ready; from any other device on the same network, open homegames.link.

What happens on first boot

1. The homegames launcher starts homegames-core — the whole server, on port 9801 — and opens your browser when it responds. Game sessions get their own ports (8300–8400) as games launch.
2. The server registers with homegames.link over an outbound connection and heartbeats every few seconds, so browsers on your network that visit homegames.link get redirected to it.
3. That's it — by default everything runs over plain HTTP on your LAN.

Enabling HTTPS (optional)

Turn on secure connections from the dashboard's settings. The server asks the Homegames API which *.homegames.link subdomain your network is assigned, generates a keypair locally, and submits a certificate signing request — the private key never leaves your machine. The key and certificate are stored in your OS's application-data directory (e.g. ~/Library/Application Support/homegames/hg-certs on macOS, ~/.homegames/hg-certs on Linux) and renew automatically when they near expiry.

LAN-only / dev mode

You can also run the server directly, without the launcher. This is the fastest loop for development (it's how the games in the docs are typically iterated on locally):

# the whole server — dashboard + web client on port 9801
cd homegames-core && npm install && npm start

Then open http://localhost:9801. To boot straight into one game instead of the dashboard (great while building a game), set START_PATH in homegames-core's config.json to that game's index.js.

Configuration

Configuration lives in config.json, overridden key-by-key by a user config in your OS's application-data directory (that's what the dashboard's settings UI writes), and any key can be overridden with an environment variable of the same name. The keys you're most likely to touch:

Ports & firewall

Devices on your LAN need to reach the server on:

• 9801 — the dashboard, the web client, and its WebSocket (one port for everything)
• 8300–8400 — game session WebSockets (players are redirected into this range when a game launches)

Nothing needs to be reachable from the internet — no port forwarding, no router configuration. The homegames.link connection is outbound-only.

Troubleshooting

• "No Homegames servers found" at homegames.link — the visiting device and the server aren't on the same network as far as the internet can tell. Guest wifi, VLANs, and VPNs on either device are the usual culprits (the service matches server and visitor by public IP). Also confirm the server is actually running and LINK_ENABLED is true — a server that stops heartbeating drops off the list within about 90 seconds.
• Stuck on "setting up a secure connection" — the certificate is still being issued (usually a minute or two), or it's been issued and the server just needs a restart to start serving it. If it never resolves, check the server logs for the cert flow.
• Games won't launch at all — game sessions need Docker (the server builds and runs a homegames-runner container per session). Install Docker, or set FORK_SESSIONS_ENABLED=true to use plain child processes.
• Dashboard loads but games don't — launching a game redirects the browser to a port in the 8300–8400 range; a firewall on the server blocking that range is the usual cause.
• Works on the server, not on phones — same as above, or client isolation ("AP isolation") is enabled on the wifi network, which blocks LAN devices from talking to each other. Fully-offline play also works by visiting http://<server LAN IP>:9801 directly (homegames.link itself needs internet).

Hosting the whole platform

Everything behind homegames.io is open source too — the API, the website, the link service, and the background worker. Running your own complete platform (your own catalog, studio, and cert authority) is possible but is a much bigger project: the API alone wants MongoDB, RabbitMQ, a Forgejo git server, and Docker, and the cert flow needs a domain with DNS you control. If you're seriously interested, start with the READMEs in the homegamesio GitHub org — each repo documents its own moving parts — or email joseph@homegames.io.

Something wrong or confusing on this page? Email joseph@homegames.io or open an issue on GitHub.