Making Tmux settings permanent with Home Assistant

If you’ve ever tried customising tmux on Home Assistant OS, you’ll have noticed one frustrating thing: your changes don’t survive reboots.

💡 Why this happens Home Assistant OS is largely immutable. Many user-level config changes (like .tmux.conf) don’t persist or get overwritten during startup.

After a fair bit of trial and error, I landed on a simple and reliable workaround.

🧠 The Idea

Instead of fighting the system, let it initialise normally… then patch tmux afterward.

⚙️ Approach Store your custom config in /config (persistent)Use a startup script to inject it into .tmux.conf

📁 Step 1: Create a Persistent Tmux Config

Create the file /config/tmux_additional.conf with the following content:

# Change Bind Keys
set -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# Change bottom of the screenbar colours
set -g status-style "fg=white,bg=blue"

# Basic Settings
#set-option -g mouse on           # Enable mouse support
set-option -g history-limit 10000 # Increase scrollback buffer
set-option -g escape-time 0      # Reduce escape delay

# Tmux Plugin Manager (TPM) setup
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible' # Sensible defaults

# Initialize TPM (add at the very end of the file)
run-shell "~/.config/tmux/plugins/tpm/tpm"

📌 Note The /config directory is persistent on Home Assistant OS, so anything stored here survives reboots.

⚡ Step 2: Create the Init Script

Now create the script to add the additional configuration on startup, /config/fix_tmux_init.sh:

#!/bin/bash

echo "source /config/tmux_additional.conf" >> ~/.tmux.conf

This appends a line telling tmux to load your custom config.

🚀 Step 3: Run It on Startup

You’ll need to ensure this script runs during system startup.

🔧 Options Add it to an init scriptCall it via a Home Assistant automationCall it using the app page's settings

I used the init_commands in the advanced shells configuration

The key requirement: it runs after the user environment is ready.

🧪 Why This Works

✅ /config is persistent ✅ .tmux.conf is rebuilt/reset ✅ Script re-injects your config every boot

It’s simple, slightly hacky—but very effective.

⚠️ Gotcha: Duplicate Entries

One issue: this script appends the same line every time it runs.

⚠️ Problem You’ll eventually end up with multiple identical source lines in .tmux.conf. While this isn't actually an issue for the advanced shell running in a docker container like on the yellow, it is best practice.

✅ Improved Version

This ensures the line is only added once.

#!/bin/bash

grep -qxF 'source /config/tmux_additional.conf' ~/.tmux.conf || echo 'source /config/tmux_additional.conf' >> ~/.tmux.conf

🧰 Make It Executable

Don’t forget to run:

chmod +x /config/fix_tmux_init.sh

💬 Final Thoughts

Home Assistant OS isn’t designed for deep shell customisation—but with a few small workarounds, you can still tailor your environment.

🧩 What this gives you Persistent tmux configClean separation of custom settingsEasy future tweaks

If you spend a lot of time in the terminal on your Home Assistant Yellow, this makes a noticeable difference.