[Share/Guide] How to run ConvertX as a Home Assistant Add-on on Raspberry Pi

[Emic-fox]

Hi everyone!

I recently wanted to run ConvertX on my Home Assistant OS setup (running on a Raspberry Pi). To make things clean and reusable, I wrapped it into a local Home Assistant App.

All possible ConvertX environment variables are mapped directly into the Home Assistant UI options, making it very easy to configure right from the dashboard. I wanted to share my configuration so anyone can replicate this setup in just a few minutes.

Please note that English is not my native language, so I used an AI assistant to help me write this guide and keep it clear for everyone.

🚀 How to Install

1. Connect to your Raspberry Pi using Samba, SSH, or the File Editor add-on.
2. Navigate to your local directory and create a new folder named convertx inside the addons directory:
   Path: /addons/convertx/
3. Download the following archive containing the 4 required files and extract/paste them inside that folder:
   👉 config.zip
4. Go to your Home Assistant Dashboard -> Settings -> Apps.
5. Click the Install App button in the bottom right corner.
6. Click the three dots in the top right corner and select Check for updates.
7. You will see a new category called Local Add-ons featuring ConvertX.
8. Click on it, hit Install, adjust your settings in the Configuration tab (do not forget to change the JWT secret), start it up, and click the Open Web UI button to access the interface.

📂 Behind the Scenes: The Setup Structure

If you are curious about how this works or want to tweak things yourself, here is a quick breakdown of what the 4 files inside /addons/convertx/ do:

1. config.yaml This is the configuration file read by Home Assistant OS. It defines the add-on's name, description, and links all the ConvertX environment variables to the Home Assistant options UI for easy editing.

2. Dockerfile This handles the actual installation of ConvertX. It builds the lightweight container environment needed to run the application natively on your Pi.

3. run.sh A simple entrypoint script used by the Home Assistant supervisor to start the add-on. It handles the initial boot sequence and launches our execution script.

4. env-from-options.js Since ConvertX ships with Bun, I wrote this quick JavaScript script to read the options you saved in the Home Assistant UI and dynamically inject them as environment variables to start the ConvertX service.

---

Feel free to ask any questions if you run into trouble setting it up! 😊