Install directly on Node.js
Use this on macOS and Windows (where Docker can't see your Chromecasts), or on any computer without Docker.
The client is a handful of self-contained files with no node_modules to install: main.mjs (the client),
certs.mjs (the certificate generator), a shared rolldown-runtime-….mjs and
cast_channel.proto. Keep them together in one folder.
1. Install Node.js
The client needs Node.js 22.12 or newer (any later version is fine).
- macOS and Windows: the installer from nodejs.org, or
brew install node@22on macOS. - Linux: your distribution's package if it's new enough (
node --version), otherwise NodeSource or nvm.
Older Node.js
If the computer can't run Node.js 22, in order of preference:
- Use Docker if the host is Linux. The image brings its own Node.js 22 for amd64, arm64, arm/v7 and arm/v6, so a Raspberry Pi 1 or Zero with an old system Node.js still works.
- Install a newer Node.js beside the old one, without touching the system's: with
nvm (
nvm install 22), or by unpacking the official binary from nodejs.org into/opt/node22and starting the client with/opt/node22/bin/node. For a Raspberry Pi 1 or Zero (ARMv6), nodejs.org has no official build: use the community builds at unofficial-builds.nodejs.org (linux-armv6l). - Node.js 18.17 to 22.11, at your own risk: the client starts, serves HTTPS and answers its health check on Node.js 18 and 20, and the newest Node.js feature it uses arrived in 18.17. But only 22.12 and newer are tested, and Node.js 18 and 20 no longer get security fixes. Use them only to bridge until you can upgrade.
Older than 18.17 does not work.
2. Get the client's files
Copy them out of a published image (no build tools needed, only Docker on any computer):
docker create --name acc-files registry.gitlab.com/jlaramie/alexa-chromecast:2.0.3
docker cp acc-files:/opt/acc/. ./alexa-chromecast/
docker rm acc-files
Then copy the alexa-chromecast folder to /opt/alexa-chromecast (Linux and macOS) or C:\alexa-chromecast
(Windows) on the client's computer.
Or build them from the source:
git clone https://gitlab.com/jlaramie/alexa-chromecast.git
cd alexa-chromecast
corepack enable
corepack yarn@4.18.0 install
corepack yarn@4.18.0 workspace @acc/client build # writes apps/client/dist/
sudo mkdir -p /opt/alexa-chromecast && sudo cp apps/client/dist/* /opt/alexa-chromecast/
3. Run it
Run it from the folder that holds config.json: relative paths in config.json (such as server.key) are relative
to the folder the client starts in.
cd ~/.config/alexa-chromecast
node /opt/alexa-chromecast/main.mjs # or: --config /path/to/config.json
You should see discovery: device added for each Chromecast within a few seconds. Press Ctrl+C to stop it, then
set it up to start on its own.
4. Keep it running
Linux (systemd)
Create a user for it (or use your own), then /etc/systemd/system/alexa-chromecast.service:
[Unit]
Description=alexa-chromecast home client
After=network-online.target
Wants=network-online.target
[Service]
User=alexa
WorkingDirectory=/home/alexa/.config/alexa-chromecast
ExecStart=/usr/bin/node /opt/alexa-chromecast/main.mjs
Restart=on-failure
Environment=LOG_LEVEL=info
[Install]
WantedBy=multi-user.target
With a Node.js installed beside the system's, put its full path in ExecStart (for example
/opt/node22/bin/node). Then:
sudo systemctl daemon-reload
sudo systemctl enable --now alexa-chromecast
journalctl -u alexa-chromecast -f # logs
macOS (launchd)
Save as ~/Library/LaunchAgents/com.example.alexa-chromecast.plist, with your user name and Node.js path (which node):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.example.alexa-chromecast</string>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/node</string>
<string>/opt/alexa-chromecast/main.mjs</string>
</array>
<key>WorkingDirectory</key><string>/Users/you/.config/alexa-chromecast</string>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>/Users/you/Library/Logs/alexa-chromecast.log</string>
<key>StandardErrorPath</key><string>/Users/you/Library/Logs/alexa-chromecast.log</string>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/com.example.alexa-chromecast.plist
macOS asks once whether Node.js may accept incoming connections and find devices on the local network: allow both.
Windows
Run it as a service with NSSM (nssm install alexa-chromecast): set the path to node.exe,
the argument C:\alexa-chromecast\main.mjs, and the startup directory to the folder that holds config.json. Or use
Task Scheduler with the trigger "At startup".
Allow inbound TCP 20846 in Windows Defender Firewall, and allow Node.js on private networks when Windows asks.
Updating
Replace the files in /opt/alexa-chromecast with the new version's (step 2) and restart the service. After an
update that adds device features, say "Alexa, discover devices".