Home Claw

Home Claw is a self-hosted home entertainment dashboard.

Run

Node.js 20.19 or newer is required.

npm exec -y home-claw

The server starts at http://localhost:5567. To use another port or bind address:

npm exec -y home-claw -- --port 3000 --hostname 127.0.0.1

PORT and HOST are also supported.

HTTPS on the local network

The access panel's LAN tab offers the same address two ways, HTTP and HTTPS, each with its own link and QR code. HTTPS is the one a phone browser will let use a microphone.

Picking HTTPS is the whole setup: the server issues a certificate for this machine on the spot and opens its HTTPS listener on the plain port plus one, so https://192.168.1.20:5568 is live before the QR code appears. Nothing is published beyond the local network — the same interface, no router port forwarding — and localhost still means the machine Home Claw runs on, so other devices need the LAN address.

The certificate covers every LAN address this machine has, plus localhost and its .local name, and lasts 825 days. It is issued by mkcert, which Home Claw downloads for itself — one static binary into ~/.home-claw/bin, no package manager and no privileges — when the machine does not already have it. An mkcert already on PATH is used as it is.

mkcert also tries to put its root certificate in this machine's trust stores, which is what makes the address trusted rather than merely encrypted. That step needs an administrator, so a server running in the background usually cannot finish it. Either way the address works; what changes is what devices say the first time they open it:

• Root installed: browsers here trust the address outright. Other devices trust it once mkcert's root is installed there too — mkcert -CAROOT prints the folder holding the file to send over.
• Root not installed: every device warns once on the first visit. Accept it and the address works from then on, microphone included. The panel says which of the two happened.

HOME_CLAW_MKCERT_DOWNLOAD=off keeps the server off the network; it then falls back to openssl and issues its own certificate, with the same one-time warning.

Only an approved device can turn HTTPS on, since it writes to the server's disk and opens a port. If mkcert cannot be downloaded and the machine has no openssl either, the panel shows the commands that do the same by hand.

Certificates from elsewhere, a different port, or no HTTPS at all:

npm exec -y home-claw -- --tls-cert /path/cert.pem --tls-key /path/key.pem
npm exec -y home-claw -- --https-port 8443
npm exec -y home-claw -- --no-https

HOME_CLAW_TLS_CERT, HOME_CLAW_TLS_KEY, HOME_CLAW_TLS_DIR and HTTPS_PORT do the same from the environment. A certificate that already exists at those paths is served from startup; by default they live in ~/.home-claw/tls.

Karaoke microphone access

Spoti4 Karaoke can record a microphone from any device that can reach Home Claw, such as a guest's phone — no device trust needed. Mobile browsers only allow microphone capture from a secure context, so open Home Claw through a trusted HTTPS address before using the access QR code: the LAN tab's HTTPS option above, an HTTPS reverse proxy, or Tailscale Serve. Plain LAN HTTP addresses cannot request microphone permission.

Tailscale Serve is the shortest way to one from outside the house. Run this once on the machine running Home Claw, with the port it is listening on:

tailscale serve --bg localhost:5567

The VPN (Tailscale) tab of the access panel then points its link and QR code at the resulting https://<machine>.<tailnet>.ts.net address instead of the plain http://100.x.y.z:5567 one. It picks that up on its own, and only from a Serve handler that forwards to this server's own port, so a Serve config put up for some other app is left alone.

The microphone is off by default. On the remote Activity banner, tap the Karaoke microphone button to join or leave the live performance. Turning off a phone microphone does not finish the take: Home Claw automatically saves one combined music-and-vocals recording when the song ends or the player switches away. The playback profile keeps the original, and every singer profile gets its own copy in Recordings. Any device can search for and save YouTube karaoke videos. Trust is still required for uploading local videos, deleting videos or recordings, and for the device playing the song, which is what receives and mixes the live microphone audio.

Choosing a YouTube result from an active karaoke session adds it to the queue immediately while its offline video downloads in the background. The server prints that transfer's metadata, progress, completion, and failures with the [karaoke-download] prefix and a request ID; queue command delivery uses the existing [activity] log.

Run in the background

Installing the daemon keeps the server running across logins and reboots, without a terminal held open for it:

npm exec -y home-claw -- --install-daemon

That installs a per-user service — a launchd LaunchAgent on macOS, a systemd user unit on Linux, a logon Scheduled Task on Windows — running the server with the --port and --hostname given alongside the flag, from the directory the command was run in, so it keeps using the same ./data folder. Its output goes to ~/.home-claw/logs/home-claw.log.

npm exec -y home-claw -- --daemon-status     # what is installed, as JSON
npm exec -y home-claw -- --uninstall-daemon  # stop and remove the service

On a headless Linux host the user session has to survive logout for the unit to keep running: loginctl enable-linger $USER.

Data

Home Claw stores profiles and downloaded media in ./data by default, relative to the directory where the command is run. The browser on the machine running the server can move that folder from the profile menu, under Change data folder. See docs/profile-storage.md in the repository for that and for the available data-directory environment variables and migration behavior.