Installing the SmartHomeEntry agent
The agent is a small program in your home network. It opens an outbound connection to our server and makes the chosen service available at an HTTPS address - no ports opened on your router. Pick the installation method that matches your hardware.
Before you start
- Create an account and choose a plan.
- In the dashboard click “Add installation”, choose the system (e.g. Home Assistant) and enter its address in your local network.
- The dashboard shows an install token and ready-made commands that already contain it. The token is single-use and valid for up to 30 minutes - if it expires, generate a new one in the dashboard.
Below are the same steps so you can review them before buying. In the commands, replace <TOKEN> with the token from the dashboard.
Choose an installation method
For Home Assistant OS and Supervised installations. The agent runs as an add-on: no terminal, no commands, updates right in the HA interface.
Add the add-on repository
Click the button - your Home Assistant opens with the repository address filled in. Confirm adding it.
Or manually: Settings → Add-ons → Add-on Store → ⋮ (top right) → Repositories, then paste the address:
https://github.com/szyderca84/SmartHomeEntry-HA-AddonInstall the add-on
Find “SmartHomeEntry Agent” in the list and click Install. If you cannot see it, reload the store page.
Paste the token
In the add-on, open the Configuration tab and paste the token from the SmartHomeEntry dashboard into the install_token field.
Save and start
Click Save, then Start on the Info tab. The agent connects within a few seconds and the dashboard shows it as online.
On Home Assistant OS, do not install the agent with the curl command from the Linux tab or via the “Terminal & SSH” add-on - it runs in a container without systemd, so the agent would not survive a restart. Running Home Assistant Container or Core (no Supervisor)? Use the Docker or Linux tab.
Troubleshooting
Where to find the logs
SmartHomeEntry Agent add-on → Log tab (the Refresh button shows the latest entries). It shows whether the agent fetched its configuration and set up the tunnel.
- The log reports an invalid or expired token - it was already used or 30 minutes have passed. Generate a new one in the dashboard, paste it in Configuration and restart the add-on.
- The add-on is not listed after adding the repository - in the store choose ⋮ → Check for updates and reload the page.
- The dashboard shows the agent online but the HTTPS address returns an error - check the service’s local address in the dashboard. It must be reachable from the device the agent runs on (usually port 8123 for Home Assistant).
For servers and NAS devices with Docker (Synology, QNAP, Unraid, plain Linux) and for Home Assistant Container. The agent runs as a container that comes back up after a reboot.
Generate a token in the dashboard
Dashboard → “Add installation”. You get the command below with the token and service address already filled in - just copy it.
Start the container
On a machine that can reach the service in your local network, run:
docker run -d --name smarthomeentry-agent \ -e SMARTHOMEENTRY_INSTALL_TOKEN=<TOKEN> \ -e SMARTHOMEENTRY_API_URL=https://control.smarthomeentry.com \ -e SMARTHOMEENTRY_LOCAL_ADDR=localhost:8123 \ --network host \ --restart unless-stopped \ smarthomeentry/smarthomeentry-agent:latestSMARTHOMEENTRY_LOCAL_ADDR is the service address as seen from this host: localhost:8123 for Home Assistant on the same machine, or e.g. 192.168.1.20:5000 for a NAS on your network.
Docker Desktop (macOS, Windows) does not support --network host. Leave that line out and use host.docker.internal instead of localhost (e.g. host.docker.internal:8123).
Requirements: Docker Engine 20+ or Docker Desktop, internet access (outbound connection).
Troubleshooting
Where to find the logs
docker logs -f smarthomeentry-agentIs the container running:
docker ps --filter name=smarthomeentry-agent- The container keeps restarting and the log mentions the token - it expired or was already used. Generate a new one in the dashboard, remove the smarthomeentry-agent container and run the command again:
docker rm -f smarthomeentry-agent - The tunnel is up but the service does not respond - the container must be able to reach the local address. On Linux keep --network host, on Docker Desktop use host.docker.internal.
- The dashboard shows the agent online but the HTTPS address returns an error - check the service’s local address in the dashboard. It must be reachable from the device the agent runs on (usually port 8123 for Home Assistant).
For Debian, Ubuntu, Raspberry Pi OS, Fedora and RHEL with systemd. The script installs a .deb or .rpm package (amd64, arm64, armhf) and a systemd service that starts with the system.
Generate a token in the dashboard
Dashboard → “Add installation”. You get the command below with the token and service address already filled in - just copy it.
Run the install script
Paste the command into a terminal on the device (e.g. over SSH on a Raspberry Pi):
curl -sSL https://control.smarthomeentry.com/api/install/<TOKEN> | sudo bashPrefer to read what you run first? Download the script to a file, review it, then run it:
curl -sSL https://control.smarthomeentry.com/api/install/<TOKEN> -o install.sh less install.sh sudo bash install.shDone
The agent runs in the background as a systemd service and starts again after a reboot. Its configuration is in /etc/smarthomeentry/agent.env.
If there is no package for your distribution or architecture, the script falls back to Docker - then check the logs as described in the Docker tab. On macOS the script always uses Docker.
Requirements: root privileges (sudo), systemd, curl, internet access.
Troubleshooting
Where to find the logs
journalctl -u smarthomeentry-agent -fService status:
systemctl status smarthomeentry-agentRestart the service:
sudo systemctl restart smarthomeentry-agent- The script stops with “Run as root” - run the command with sudo, as shown above.
- The agent does not connect and the log mentions the token - generate a new token in the dashboard and run the install command again; the script overwrites the configuration.
- The dashboard shows the agent online but the HTTPS address returns an error - check the service’s local address in the dashboard. It must be reachable from the device the agent runs on (usually port 8123 for Home Assistant).
Still not working?
Write to us and include the last few lines of the agent log - that is the fastest way to a diagnosis.