A name and a port

The skill reaches your home client from the internet, so your house needs a stable name and an open port.

A stable name

Your internet provider can change your home's public IP address at any time, so give it a name that follows it: a dynamic DNS name. Any of these work:

  • a free dynamic DNS service such as DuckDNS or No-IP, with its updater running on the client host or your router;
  • your router's own dynamic DNS feature;
  • a record in a domain you own (for example in Route 53), updated by a script.

This guide uses home.example.net. Use your own name everywhere you see it.

A fixed public IP address also works, but a name is better: a free Let's Encrypt certificate needs one.

The port forward

The client listens on TCP port 20846 (change it with port in config.json).

On your router, forward external TCP port 20846 (or any external port you like) to port 20846 on the computer that runs the client. Give that computer a fixed address on your network (a DHCP reservation), or the forward breaks when its address changes.

The endpoint URL

The skill calls your client at:

https://home.example.net:20846/askhomeskill

Use your name and your external port. You enter this URL on the settings site.

  • It must be https://. The skill refuses http://, because commands carry your Amazon sign-in.
  • The host must match the name in the client's TLS certificate.
  • The path is always /askhomeskill. Requests to any other path are logged by the client with a reminder of this URL.

Check it from outside

Once the client runs, check the forward from a network other than your home's (for example a phone off Wi-Fi):

curl -s https://home.example.net:20846/health        # {"status":"ok"}

With your own CA instead of Let's Encrypt, add --cacert ca.crt. If you turned on client certificates (mTLS), also add --cert client.crt --key client.key.

Some routers can't reach their own public address from inside the network ("NAT loopback"), so a check from inside your house can fail even when the forward works.