[FR]: Add `~/.config/helium-flags.conf` support to helium-wrapper

[s6muel]

Description

Allow users to append flags via helium-flags.conf at runtime

Who's implementing?

• I'm willing to implement this feature myself

The problem

Linux users expect to be able to set flags at runtime (particularly important with Wayland) with Chromium-based applications via a *.conf file.

Possible solutions

AUR packaging implements this downstream in the wrapper via bash script¹, and appends to the binary call. The following version only has support for {$XDG_CONFIG_HOME}/helium-flags.conf:

[Note we add support to set flags via /etc/helium-flags.conf and environment var HELIUM_USER_FLAGS downstream, which is omitted in this patch.]

From b6babf26b1f537b4e751315d2743d218c1d1f506 Mon Sep 17 00:00:00 2001
From: Sam Sinclair <sam@playleft.com>
Date: Wed, 31 Dec 2025 10:59:52 +1100
Subject: [PATCH] feat: add helium-flags.conf support

---
 package/helium-wrapper.sh | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/package/helium-wrapper.sh b/package/helium-wrapper.sh
index 191711c..30664ee 100755
--- a/package/helium-wrapper.sh
+++ b/package/helium-wrapper.sh
@@ -11,7 +11,44 @@ export CHROME_VERSION_EXTRA="custom"
 CHROME_WRAPPER="$(readlink -f "$0")"
 HERE="$(dirname "$CHROME_WRAPPER")"
 
+# Gather user config dir and .conf
+XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-"$HOME/.config"}"
+
+USR_CONF="${XDG_CONFIG_HOME}/helium-flags.conf"
+
+FLAGS=()
+
+append_flags_file() {
+  local file="$1"
+  [[ -r "$file" ]] || return 0
+  local line safe_line
+  # Filter comments & blank lines
+  while IFS= read -r line; do
+    [[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
+    # Sanitise: block command substitution; prevent $VAR and ~ expansion
+    case "$line" in
+      *'$('*|*'`'*)
+        echo "Warning: ignoring unsafe line in $file: $line" >&2
+        continue
+        ;;
+    esac
+    # Disable globbing during eval
+    set -f
+    # Prevent $VAR and ~ expansion while allowing eval to parse quotes & escapes
+    safe_line=${line//$/\\$}
+    safe_line=${safe_line//~/\\~}
+    eval "set -- $safe_line"
+    # Enable globbing for rest of the script
+    set +f
+    for token in "$@"; do
+      FLAGS+=("$token")
+    done
+  done < "$file"
+}
+
+append_flags_file "$USR_CONF"
+
 export CHROME_WRAPPER
 export LD_LIBRARY_PATH="$HERE:$HERE/lib:$HERE/lib.target${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
 
-exec "$HERE/chrome" "$@"
+exec "$HERE/chrome" "${FLAGS[@]}" "$@"
-- 
2.52.0

Additional context

This implementation has been stable since October 20th, 2025 ².

Official Arch packaging for Chromium³ utilises a C based chromium-launcher which this implementation is a simplified reproduction of.

Footnotes

1. https://aur.archlinux.org/cgit/aur.git/commit/?h=helium-browser-bin&id=f2bf054511b851263caa9288f66b2d3b4a412fd7 ↩

2. https://aur.archlinux.org/cgit/aur.git/commit/?h=helium-browser-bin&id=0b2ff96f5b3772b9592cb7093e118ffd4a3404cb ↩

3. https://gitlab.archlinux.org/archlinux/packaging/packages/chromium/-/blob/main/PKGBUILD?ref_type=heads#L31 ↩

[dumbmoron]

LGTM, although please make sure it passes shellcheck

[s6muel]

Patch updated to fix SC2016 on Ln30. We now escape rather than single-quote (where shellcheck expected us to double quote).

If you'd like me to include a SYS_CONF for system wide flags just let me know.

From 6a549ecb13ba6da7be49bf4192dab8b36e21c9be Mon Sep 17 00:00:00 2001
From: Sam Sinclair <sam@playleft.com>
Date: Wed, 31 Dec 2025 10:59:52 +1100
Subject: [PATCH] feat: add helium-flags.conf support

---
 package/helium-wrapper.sh | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/package/helium-wrapper.sh b/package/helium-wrapper.sh
index 191711c..a48fb58 100755
--- a/package/helium-wrapper.sh
+++ b/package/helium-wrapper.sh
@@ -11,7 +11,44 @@ export CHROME_VERSION_EXTRA="custom"
 CHROME_WRAPPER="$(readlink -f "$0")"
 HERE="$(dirname "$CHROME_WRAPPER")"
 
+# Gather user config dir and .conf
+XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-"$HOME/.config"}"
+
+USR_CONF="${XDG_CONFIG_HOME}/helium-flags.conf"
+
+FLAGS=()
+
+append_flags_file() {
+  local file="$1"
+  [[ -r "$file" ]] || return 0
+  local line safe_line
+  # Filter comments & blank lines
+  while IFS= read -r line; do
+    [[ "$line" =~ ^[[:space:]]*(#|$) ]] && continue
+    # Sanitise: block command substitution; prevent $VAR and ~ expansion
+    case "$line" in
+      *\$\(*|*\`*)
+        echo "Warning: ignoring unsafe line in $file: $line" >&2
+        continue
+        ;;
+    esac
+    # Disable globbing during eval
+    set -f
+    # Prevent $VAR and ~ expansion while allowing eval to parse quotes & escapes
+    safe_line=${line//$/\\$}
+    safe_line=${safe_line//~/\\~}
+    eval "set -- $safe_line"
+    # Enable globbing for rest of the script
+    set +f
+    for token in "$@"; do
+      FLAGS+=("$token")
+    done
+  done < "$file"
+}
+
+append_flags_file "$USR_CONF"
+
 export CHROME_WRAPPER
 export LD_LIBRARY_PATH="$HERE:$HERE/lib:$HERE/lib.target${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
 
-exec "$HERE/chrome" "$@"
+exec "$HERE/chrome" "${FLAGS[@]}" "$@"
-- 
2.52.0

[Anonx15]

#!/usr/bin/env bash
# Helium Browser wrapper
# Reads persistent flags from /etc/helium-flags.conf and ~/.config/helium-flags.conf
# Format: one flag per line, # for comments

set -euo pipefail

chrome_wrapper="$(readlink -f "$0")"
here="$(dirname "$chrome_wrapper")"

export CHROME_WRAPPER="$chrome_wrapper"
export CHROME_DESKTOP="helium.desktop"
export CHROME_VERSION_EXTRA="Helium"
export LD_LIBRARY_PATH="${here}${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"

# Config file paths - loaded in order: system → user
sys_conf="/etc/helium-flags.conf"
usr_conf="${XDG_CONFIG_HOME:-${HOME}/.config}/helium-flags.conf"

declare -a flags=()

# Read flags from config file
# Skips comments (#) and blank lines
# Each line becomes one argument to chrome
read_flags() {
    local file="$1"
    [[ -r "${file}" ]] || return 0
    
    local lines=()
    mapfile -t lines < "${file}"
    
    for line in "${lines[@]}"; do
        [[ "${line}" =~ ^[[:space:]]*(#|$) ]] && continue
        flags+=("${line}")
    done
}

read_flags "${sys_conf}"
read_flags "${usr_conf}"

# Launch chrome with config flags + command line args
exec "${here}/chrome" "${flags[@]}" "$@"

[s6muel]

G'day,

Thanks to a downstream report an issue has been identified with this patch. The flag parsing logic is dependent on bash but the wrapper declares #!/bin/sh. The script will error out where, for example, /bin/sh doesn't resolve to bash (i.e., ls -l /bin/sh).

It's worth noting that upstream Chromium's wrapper¹ explicitly declares bash to make use of -a in the binary call, while leaving flags support to downstream packaging. I thought this was worth noting as Helium appears to be moving towards official downstream packaging on Linux (i.e., Copr).

If you'd like me to amend the previous patch to include the bash declaration just let me know. But perhaps it might be better to port in Chromium's wrapper and patch in flags support at the packaging stage?

Footnotes

1. https://source.chromium.org/chromium/chromium/src/+/main:chrome/installer/linux/common/wrapper ↩