Posted on ::

I've put together ha-rex-server, a Home Assistant app (what Home Assistant used to call add-ons) that runs a Rex terminal server on your Home Assistant machine.

Rex is a terminal multiplexer, like tmux or screen. A multiplexer keeps your terminal sessions running on the server, so you can split them into tabs and panes, disconnect, and pick up exactly where you left off later. The sessions live on the machine running the server, not in the app you're looking at them through.

The difference with Rex is the client. Instead of attaching from another terminal, you connect from a native macOS or iOS app (or the rex command-line tool). Running it on the Home Assistant box means I can open terminals from my laptop or phone, and anything I leave running is still there when I come back.

The Home Assistant machine is on all the time anyway. I wanted another remote host I could connect to when my main Mac is off, for the times I need to reach something on my home network.

The terminals run inside the app's container, not on the Home Assistant host, so this isn't a replacement for the Terminal & SSH app. A shell on the host was never the goal; I just wanted another target to connect to. The container only sees its own data folder, not the host's files.

How the app works

Every Home Assistant app is a Docker container. When you install an app from the store, Home Assistant doesn't compile anything on your machine: it downloads a prebuilt container image and runs it. So the main job of this project is producing that image and keeping it up to date.

A GitHub Actions workflow builds the image on every release and publishes it to GitHub's container registry as ghcr.io/aranw/ha-rex-server:<version>. One image covers both flavours of hardware Home Assistant runs on: it's built for amd64 (Intel/AMD boxes) and arm64 (Raspberry Pi and most other boards) in a single package, and Home Assistant picks the right one for your machine automatically when it pulls it.

The image doesn't contain Rex itself. Rex publishes builds across three release channels: stable, preview, and snapshot. If I baked a particular Rex build into the image, switching channels would mean publishing a separate image for each one. Instead, the image contains only the base system, the startup scripts, and the signing key for Rex's package repository, which lets it verify that the packages it downloads are genuinely from Rex.

When the app starts, a small setup script runs first. It reads the channel you picked in the Configuration tab (preview by default), downloads Rex from that channel's package repository, and installs it. A second script then starts the Rex server itself, and the container's process supervisor keeps it running. This all happens on every start, which gives you two things for free:

  • switching channels (or moving back from snapshot to preview) is just a dropdown change and a restart;
  • restarting the app also picks up the newest Rex build on your current channel, without waiting for me to publish a new app version.

The trade-off is that the app needs network access at startup to fetch Rex, and the exact Rex version isn't pinned by the app version. For a project tracking a fast-moving beta, that's the behaviour I want. One catch: restarting the app stops anything running in your sessions, so save your work before you flip that dropdown.

Connecting with Tailscale

The easiest way to connect is over Tailscale. Rex has Tailscale built in, so the Home Assistant machine doesn't need Tailscale installed separately, and you don't need to open any ports on your local network or router.

Paste a one-time Tailscale auth key into the app settings and start the app. It joins your Tailscale network as its own device (ha-rex by default, which you can change in the settings) and sets up an HTTPS certificate automatically. For that to work, your tailnet needs MagicDNS and HTTPS certificates turned on (both live in the Tailscale admin console under DNS). That's a Rex requirement, not something the app can set up for you. The login is saved in the app's data folder, so you only need the auth key once and it stays signed in across restarts and backups.

Once it's running, add https://ha-rex.<your-tailnet>.ts.net under Add Remote Host… in Rex for Mac, or connect from the command line:

rex -S https://ha-rex.<your-tailnet>.ts.net ls

If you don't use Tailscale, there is also an optional plain HTTP listener you can turn on for a trusted local network or VPN. It is off by default because it doesn't require a login, so anyone who can reach that port on your network can open a terminal inside the app container.

Installing it

In Home Assistant, go to Settings > Apps > App store > ⋮ > Repositories and add:

https://github.com/aranw/ha-rex-server

Then install Rex Server from the store, add your Tailscale auth key in the Configuration tab, and start the app.

The code and full setup instructions are on GitHub at github.com/aranw/ha-rex-server.