Configuration
The home client reads one file, config.json. Make a folder for it and the certificate files, for example
~/.config/alexa-chromecast/, readable only by the account that runs the client.
A first config.json
{
"https": true,
"serverKey": "server.key",
"serverCert": "server.crt",
"sharedSecret": "PASTE-THE-SECRET-FROM-THE-SETTINGS-SITE",
"accounts": [{ "id": "amzn1.account.YOUR-ACCESS-KEY-ID" }]
}
https,serverKey,serverCert: the certificate files, relative to the folder the client runs in (/appinside the Docker container, where you mount them).sharedSecret: signs every command between the skill and your client. You generate it on the settings site and paste it here exactly as shown (case matters). Until then, leave the placeholder: the client starts, and you fill it in later.accounts[].id: the Access Key ID shown on the settings site, which is your Amazon account id unless you changed it. Add one entry per Amazon account that uses this client.
The client checks the whole file when it starts and stops with a list naming every problem (never a value). Fix them all and start it again.
Adding Plex
To play from Plex by voice ("Alexa, play Planet Earth on the TV"), make an account a Plex account:
"accounts": [
{
"id": "amzn1.account.YOUR-ACCESS-KEY-ID",
"type": "plex",
"hostname": "192.168.1.20",
"token": "YOUR-PLEX-TOKEN"
}
]
hostnameis your Plex Media Server's address on your network: a name or an IP address, withouthttp://or a port.tokenis a Plex token (Plex's support article "Finding an authentication token" shows how to find one). Instead of a token you can giveusernameandpasswordfor plex.tv, unless the account uses two-factor sign-in.- A Plex Home user (for example a child's profile): add
"managed": { "username": "Kids", "pin": "1234" }.
A problem in a Plex account is only a warning when the client starts. Cast control keeps working, and only that account's voice search answers "not supported" until you fix it.
Choosing a default TV
Discovery adds a device called TV next to your real ones. "Alexa, pause the TV" goes to the last TV you named in
a command. When there is none yet (for example right after the client restarts), it goes to defaultEndpointId:
"defaultEndpointId": "Google-TV-Streamer-0123456789abcdef0123456789abcdef"
Put it at the top level for everyone, or inside an account for just that person. To find a device's id, look in the
client's logs for discovery: device added (its endpointId). See the default TV for how
Alexa picks a device when you don't name one at all.
Reference
The client reads its settings from three places, each overriding the one before:
- built-in defaults;
config.json: the path from--config, else theCONFIG_PATHenvironment variable, else./config.jsonrelative to the working directory;- command-line flags.
It checks everything at startup and stops with a list naming every bad field, never a value. Unknown keys are kept and ignored, so older files load unchanged. Empty strings count as "not set".
Every config.json key
| Key | Default | Meaning |
|---|---|---|
sharedSecret |
(required) | The secret that signs every command between the skill and this client. Generate it on the settings site and paste it exactly (case matters). A per-account sharedSecret overrides it for that account. |
port |
20846 |
Listening port: a number, or a string of digits. |
https |
false |
Serve HTTPS. true/false, 1/0, or the strings "1"/"0", which older files used. Note that the string "0" turns HTTPS on, as it did in the original client; the loader warns about strings. The skill only talks HTTPS, so production needs true. |
serverKey, serverCert |
(none) | The TLS private key and certificate (PEM). Required with https. Paths are relative to the working directory (/app in the container). |
serverCA |
(none) | A CA certificate. With requireClientCert, client certificates must chain to it (unless clientCA is set). |
clientCA |
(none) | The CA that signs client certificates, when it differs from serverCA (for example a Let's Encrypt server certificate with your own client CA). |
requireClientCert |
false |
mTLS: every request without a client certificate from clientCA/serverCA gets 403. Needs https. The skill then presents the relay client certificate uploaded on the settings site. The only exemption is GET /health from the machine itself. |
requireTokenExp |
false |
Refuse signed commands without an expiry. The current skill always sends one (60 s), so this can be turned on. |
defaultEndpointId |
(none) | The Chromecast used when Alexa addresses the virtual TV device and no TV was used recently. The ids are in the client's logs (discovery: device added) and in the Alexa app. |
accounts |
[] |
One entry per Amazon account that uses this client (below). |
Accounts
| Key | Meaning |
|---|---|
id |
Required. The account's Access Key ID from the settings site (its Amazon account id unless changed there). |
sharedSecret |
This account's secret, when it differs from the global one. |
defaultEndpointId |
This account's default TV. |
type |
"plex" makes it a Plex account (below). |
A command from an Amazon account that matches no entry uses the first account's settings (its default TV and Plex),
but always needs a valid signature: a secret is only ever taken from the matching account or the global
sharedSecret.
Plex accounts
With "type": "plex" an account can search and play from Plex by voice ("Alexa, play … on the TV").
| Key | Default | Meaning |
|---|---|---|
hostname |
(required) | The Plex Media Server's address. With https, use its *.plex.direct name. |
port |
32400 |
|
https |
false |
Talk to the server over HTTPS. |
token |
(none) | A Plex token. Used when set. |
username, password |
(none) | plex.tv sign-in, used when there is no token, and to sign in again if the server rejects the token. Accounts with two-factor authentication need a token. |
managed |
(none) | { "username": "…", "pin": "…" }: switch to that Plex Home user after signing in (pin only if the user has one). |
identifier |
(stable hash of id) |
The client id plex.tv sees. |
A problem in a Plex account is a startup warning naming the field; the client still starts, and only that account's voice-search commands answer "not supported".
Example with two Amazon accounts sharing one Plex server:
{
"https": true,
"serverKey": "server.key",
"serverCert": "server.crt",
"sharedSecret": "…64 hex characters from the settings site…",
"defaultEndpointId": "Google-TV-Streamer-0123456789abcdef0123456789abcdef",
"accounts": [
{ "id": "amzn1.account.AAAAAAAAAAAAAAAA", "type": "plex", "hostname": "192.168.1.20", "token": "…" },
{
"id": "amzn1.account.BBBBBBBBBBBBBBBB",
"type": "plex",
"hostname": "192.168.1.20",
"username": "someone@example.com",
"password": "…",
"managed": { "username": "Kids", "pin": "1234" }
}
]
}
Command-line flags
Flags override config.json. Run node main.mjs --help for the list.
| Flag | Same as |
|---|---|
-c, --config <path> |
the config file (default config.json; or env CONFIG_PATH) |
-p, --port <n> |
port |
-h, --https[=true|false] |
https (--help is long-only) |
-k, --serverKey <path> |
serverKey |
-t, --serverCert <path> |
serverCert |
-a, --serverCA <path> |
serverCA |
--clientCA <path> |
clientCA |
--requireClientCert |
requireClientCert |
--requireTokenExp |
requireTokenExp |
-s, --sharedSecret <s> |
sharedSecret. Discouraged: other users of the machine can see it in the process list. |
Environment variables
| Variable | Meaning |
|---|---|
CONFIG_PATH |
The config file, when --config is not given. |
LOG_LEVEL |
info (default), debug for Cast and Plex detail, warn, error. Logs are JSON lines; secrets, tokens and household identifiers are redacted. |
ACC_LISTEN_FILE |
Where the client records its listening address for the health check (default /tmp/acc-listen.json). |
ACC_DISCOVERY |
off disables Chromecast discovery and control (tests only). |
ACC_CAST_TAP_FILE |
Append every Cast message, allowlist-filtered, to this file (diagnostics). |
Endpoints
| Route | Purpose |
|---|---|
POST /askhomeskill |
Signed commands from the skill. Always answers HTTP 200 with one Alexa event (errors included). |
GET /health |
{"status":"ok"} when the client is up; used by the container health check. |
| anything else | 404, logged with a reminder of the expected endpoint URL. |