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 runs two things:

• a web server that serves the Homegames client (the thing browsers render games with), and
• a game server that runs the dashboard and game sessions — including the built-in games and any games you download from the catalog.

With the link service enabled, your server registers itself with homegames.link, gets its own *.homegames.link subdomain pointed at its LAN address, and is issued a real TLS certificate — so every device on your network gets a secure, zero-config connection to a server in your own house. Game traffic itself never leaves your network.

Requirements

• 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.
• Permission to bind ports 80/443 (i.e. sudo, or a port capability on Linux).
• Internet access on first boot for certificate provisioning (play itself is LAN-local).

Quick start

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/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-web
git clone https://github.com/homegamesio/homegames

cd homegames
npm install        # links the sibling repos + installs deps
npm run build      # builds the browser client bundle
sudo node index.js # sudo because the web server binds ports 80/443

Then open localhost on the server machine, or homegames.link from any other device on the same network.

What happens on first boot

The homegames launcher does three things, in order:

1. Gets your server a certificate. It 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. Issuance usually takes a minute or two on the very first boot; 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 renewed automatically when they near expiry.
2. Starts the web server — HTTPS on 443, with port 80 redirecting to it.
3. Starts the game server — the dashboard, plus one process per running game session on its own port. It also registers with homegames.link so browsers on your network get redirected to it.

LAN-only / dev mode

You can also run the two servers directly, without the launcher or the certificate flow. This is the fastest loop for development (it's how the games in the docs are typically iterated on locally), at the cost of plain HTTP:

# terminal 1 — the game server (dashboard on port 9801 by default)
cd homegames-core && npm install && npm start

# terminal 2 — the web server (port 80)
cd homegames-web && npm install && npm run build && sudo npm start

Then open http://localhost. 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 each repo's config.json; 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:

• 80 / 443 — the web client
• 9801 — the dashboard's WebSocket
• 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.
• Stuck on "setting up a secure connection" — the certificate is still being issued; first boot can take a couple of minutes. If it never resolves, check the server logs for the cert flow.
• EACCES binding port 80 — run with sudo, or grant Node the bind capability (setcap 'cap_net_bind_service=+ep' $(which node) on Linux).
• 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.

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.