Run under a process manager

A process manager restarts your host if it crashes and stops it cleanly when the machine shuts down. Combine one with Keep a room online, which reopens rooms inside the process.

The native transport is verified on Node.js 24 on macOS (Apple silicon). Test your target platform, including players joining from other networks, before you rely on it. See Run in production.

All three setups rely on the host handling SIGTERM: close the room and wait for room.closed before exiting.

systemd

/etc/systemd/system/ball2d-host.service

[Unit]
Description=Ball2D room host
After=network-online.target
Wants=network-online.target

[Service]
User=ball2d
WorkingDirectory=/opt/ball2d-host
ExecStart=/usr/bin/node host.mjs
EnvironmentFile=/etc/ball2d-host.env
Restart=on-failure
RestartSec=10
KillSignal=SIGTERM
TimeoutStopSec=15

[Install]
WantedBy=multi-user.target

/etc/ball2d-host.env

BALL2D_API_KEY=b2d_…

Make the environment file readable only by root (chmod 600), then enable the service:

Terminal

sudo systemctl daemon-reload
sudo systemctl enable --now ball2d-host
journalctl -u ball2d-host -f

RestartSec=10 keeps a crashing host from spending your per-minute room request budget.

PM2

ecosystem.config.cjs

module.exports = {
  apps: [
    {
      name: 'ball2d-host',
      script: 'host.mjs',
      kill_timeout: 15000,
      restart_delay: 10000,
      max_restarts: 20,
    },
  ],
};

Terminal

BALL2D_API_KEY="b2d_…" pm2 start ecosystem.config.cjs
pm2 save

Docker

Dockerfile

FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY host.mjs ./
USER node
CMD ["node", "host.mjs"]

Terminal

docker build -t ball2d-host .
docker run -d --name ball2d-host --restart unless-stopped \
  --stop-timeout 15 -e BALL2D_API_KEY ball2d-host

Run the container with node as PID 1, as above, so it receives SIGTERM directly. Players connect to your host over WebRTC, so check that the container's network allows direct peer connections from your players' networks.

One host per key

A key can run one room at a time. Don't scale a host to several replicas with the same key: the extra replicas are refused while the first room is open. Give each replica its own key, within your account's limit of two rooms.