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 (/app inside 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"
  }
]
  • hostname is your Plex Media Server's address on your network: a name or an IP address, without http:// or a port.
  • token is a Plex token (Plex's support article "Finding an authentication token" shows how to find one). Instead of a token you can give username and password for 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:

  1. built-in defaults;
  2. config.json: the path from --config, else the CONFIG_PATH environment variable, else ./config.json relative to the working directory;
  3. 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.