Setting up the home client
Alexa Chromecast has two halves. The skill runs in the cloud: Alexa sends it each voice command. The home client runs on a computer in your house: the skill forwards each command to it over HTTPS, and it drives your Chromecasts, Google TVs and Plex. This guide takes you from nothing to "Alexa, pause the TV".
When you say "Alexa, pause the Living Room TV":
- Alexa sends the command to the skill.
- The skill looks up your settings: your home client's address and your shared secret.
- The skill signs the command with that secret and sends it to your home client over HTTPS.
- The home client checks the signature and tells the Chromecast to pause.
What you need
- A computer that stays on, on the same network as your Chromecasts: a Raspberry Pi, a home server or a NAS. Linux is easiest. See Which install? for macOS and Windows.
- A name the internet can reach your house by, such as a dynamic DNS name like
home.example.net, and a router that can forward a port. - An Amazon account and the Alexa app.
- For voice search and play: a Plex Media Server.
The steps
- Pick a name and forward a port
- Get a TLS certificate
- Write
config.json - Install and start the client: with Docker or directly on Node.js
- Connect it on the settings site, link the skill and choose a default TV
- Check it works, and fix it when it doesn't
Which install?
| Docker | Directly on Node.js | |
|---|---|---|
| Best for | Linux hosts (Raspberry Pi, home server, NAS) | macOS, Windows, or a host without Docker |
| Needs | Docker | Node.js 22.12 or newer |
| Updates | Run a new image tag (or let Watchtower do it) | Replace the files and restart the service |
| Chromecast discovery | Needs --network host, which only works on Linux |
Works everywhere |
| Older systems | Brings its own Node.js, even on a Raspberry Pi 1 | See Older versions of Node.js |
Docker Desktop on macOS and Windows has no host networking for mDNS, so a client in a container there cannot see your Chromecasts. Use the direct install on those systems.
Several people, one house
Several Amazon accounts can share one home client. Each person signs in on the settings site, enters the same
endpoint URL and the same shared secret, and gets their own entry in config.json's accounts. Each account can
have its own Plex sign-in and its own default TV.