Skip to content

Running custom scripts in Addons

Jump to bottom
Alexandre edited this page Jul 31, 2025 · 1 revision

All supported add-ons include a built-in feature to run your own script at startup.

This is useful if you want to:

  • Install packages (e.g., drivers, fonts)

  • Patch files dynamically

  • Run startup jobs or schedule tasks (e.g., via cron)

🔧 How it works

When the add-on starts:

  1. It checks if your custom script exists.

  2. If not, it creates a ready-to-edit template.

  3. If the file exists and contains commands, it:

    • Converts it to Unix format (if needed)

    • Makes it executable

    • Executes it once at startup

📁 Where to write your script

After starting the add-on, look at the Logs.

You will see something like:

Execute /addon_configs/addon_slug/script.sh if existing

That’s the path where your script must be placed.

Typical script paths:

Case Script path
New Home Assistant OS /addon_configs/addon_slug/script.sh
Legacy installs (old Supervisor) /config/addons_autoscripts/addon_slug.sh

✏️ This is a powerful way to customize any supported add-on, without rebuilding it. Ideal for power users!
🧩 Need more help? See other examples or ask in the GitHub Discussions page.

Here is a **clear, simplified, and user-friendly GitHub Wiki page** explaining the “Running custom scripts in add-ons” feature, rewritten in the same style as your other guides:

🛠️ Running Custom Scripts in Add-ons

All supported add-ons include a built-in feature to run your own script at startup.

This is useful if you want to:

  • Install packages (e.g., drivers, fonts)
  • Patch files dynamically
  • Run startup jobs or schedule tasks (e.g., via cron)

🔧 How it works

When the add-on starts:

  1. It checks if your custom script exists.

  2. If not, it creates a ready-to-edit template.

  3. If the file exists and contains commands, it:

    • Converts it to Unix format (if needed)
    • Makes it executable
    • Executes it once at startup

📁 Where to write your script

After starting the add-on, look at the Logs.

You will see something like:

Execute /addon_configs/addon_slug/script.sh if existing

That’s the path where your script must be placed.

Typical script paths:

Case Script path
New Home Assistant OS /addon_configs/addon_slug/script.sh
Legacy installs (old Supervisor) /config/addons_autoscripts/addon_slug.sh

💡 You can create/edit this file using [Filebrowser](https://github.com/alexbelgium/hassio-addons/tree/master/filebrowser) or [CloudCommander](https://github.com/alexbelgium/hassio-addons/tree/master/cloudcommander).

🚀 Writing your script

Your script must be a shell script, starting with a line like:

#!/usr/bin/env bashio

This allows you to use special [bashio commands](https://github.com/hassio-addons/bashio) (like reading config values or logging nicely).

✅ The script will be auto-fixed (made executable, CRLF removed, correct shebang applied if needed)

✅ Examples

📅 Example 1: Run a cron job every hour 
#!/usr/bin/env bashio
echo "Starting script"

# Install cron (for Debian/Ubuntu-based add-ons)
apt-get update
apt-get install cron -yqq

# Create a job that says hello every hour
echo 'echo "hello"' > /etc/cron.hourly/hello
chmod +x /etc/cron.hourly/hello

# Start cron
service cron start & true
🔧 Example 2: Patch a startup file to add a parameter 
#!/bin/bash
echo "Starting script"

# Add environment variable to a startup script
sed -i "3a export WHOOGLE_URL_PREFIX='$(bashio::addon.ingress_entry)'" /etc/cont-init.d/99-run.sh

# Patch a mount script if needed
if ! grep -q "iocharset=utf8,rw" /etc/cont-init.d/92-smb_mounts.sh; then
  echo "Patching SMB mount options..."
  sed -i 's|cifs -o "rw,|cifs -o "iocharset=utf8,rw,|g' /etc/cont-init.d/92-smb_mounts.sh
fi

echo "...done"
🎮 Example 3: Install graphic drivers (Alpine-based add-on) 
#!/usr/bin/env bashio
apk add --no-cache mesa-dri-vc4 mesa-dri-swrast mesa-gbm xf86-video-fbdev

♻️ Run once or more?

  • The script is executed once at startup.
  • If you want your command to run regularly, set up a cron job inside the script (see Example 1).

🧪 Debugging your script

If your script isn’t running:

  • Check the Logs — you’ll see whether it was found and executed.

  • Make sure the script is:

    • Saved in the correct path
    • Starts with #!/bin/bash or #!/usr/bin/env bashio
    • Contains real commands (not just comments)

If the script contains no valid lines, it won’t run.

✅ Summary

Feature Status
Run a custom script at startup ✅
Automatically fixes CRLF and permissions ✅
Uses bashio for access to addon helpers ✅
Supports cron or scheduled jobs (via script) ✅
Script location printed in logs ✅

✏️ This is a powerful way to customize any supported add-on, without rebuilding it. Ideal for power users! 🧩 Need more help? See other examples or ask in the GitHub Discussions page.

Clone this wiki locally