[FEATURE] Generic beta-features opt-in mechanism for the stable addon

[kingpanther13]

What would you like to see?

A first-class "beta features" opt-in path for the stable addon, so operators can enable individual unstable features without switching to the dev addon channel and without setting environment variables manually.

Proposed by @julienld in #942 (comment) as a follow-up to moving ha_config_set_yaml out of the main addon UI:

As a follow-up, we could open a separate PR to add a generic beta features mechanism to the stable addon: a free-form text field with instructions pointing to docs/beta.md for users who want to opt in.

Two reasonable shapes for the implementation, not mutually exclusive:

1. Addon config text field — a single beta_features: "" field in homeassistant-addon/config.yaml's options:/schema:, parsed by homeassistant-addon/start.py into the corresponding ENABLE_* env vars before the server starts. Values would be a comma-separated list of beta feature names documented in docs/beta.md (e.g., beta_features: "yaml_config_editing").
2. Web UI integration with feat: web-based settings UI for per-tool enable/disable/pin #960 — the settings UI from feat: web-based settings UI for per-tool enable/disable/pin #960 already renders feature-gated tool stubs (ha_config_set_yaml, filesystem tools) with locked toggles and a note explaining which flag is required. A "Beta features" section at the top of /settings could expose those gates as opt-in checkboxes that, when enabled, persist to tool_config.json (or a sibling beta_config.json) and unlock the corresponding tool stubs on next restart. This keeps stable addon operators on the stable channel while still letting them opt into individual unstable tools through a UI path, and avoids the env-var-fiddling that julienld's first paragraph in refactor(addon): move ha_config_set_yaml to dev channel only (breaking — stable toggle removed, set ENABLE_YAML_CONFIG_EDITING or use dev add-on) #942 was trying to spare them.

Pairing both gives users two compatible entry points: the addon config field for operators who never open the web UI, and the /settings UI for everyone else. Both would write to the same persistence file so they stay coherent.

Why do you need this?

In #942, julienld proposed moving ha_config_set_yaml out of the stable addon's main toggle list and into a beta status — accessible only via env var or via the dev channel addon. That solves the "this should not be one click away on stable" problem for that specific tool, but leaves a gap for any operator who wants to opt in:

• Stable addon users can't easily set arbitrary env vars (HA Supervisor only honors options listed in the addon's schema:).
• Switching to the dev channel addon to get one beta feature pulls in every dev change, which is more risk than they signed up for.
• The non-addon (pip / Docker direct / uv) env var path works but excludes the addon-using majority.

A generic beta opt-in mechanism solves the "I want exactly this one risky feature on stable" case for ha_config_set_yaml today, and gives future risky-but-useful features a stable home that doesn't require either a dev channel switch or a new toggle slot in the main addon UI for every one of them.

Additional context

• Blocked on refactor(addon): move ha_config_set_yaml to dev channel only (breaking — stable toggle removed, set ENABLE_YAML_CONFIG_EDITING or use dev add-on) #942 landing (which establishes docs/beta.md and removes enable_yaml_config_editing from the stable addon UI).
• Strong integration opportunity with feat: web-based settings UI for per-tool enable/disable/pin #960 — the web settings UI already has the "feature-gated tool stub" concept and could host the opt-in toggles natively, so beta features become a first-class part of the existing settings page rather than a separate config surface.
• First feature to migrate in: yaml_config_editing (ENABLE_YAML_CONFIG_EDITING).
• Future candidates worth reviewing once the mechanism exists: filesystem tools (HAMCP_ENABLE_FILESYSTEM_TOOLS), and any other env-var-gated capabilities currently hidden from addon users.

[github-actions]

❌ Analysis failed

An error occurred:

YOLO mode is enabled. All tool calls will be automatically approved.
YOLO mode is enabled. All tool calls will be automatically approved.
Error executing tool read_file: File not found.
{
  "session_id": "a7b9c2e1-33e1-461f-ab0f-6c3dae6c3d61",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}[ERROR] {
  "session_id": "a7b9c2e1-33e1-461f-ab0f-6c3dae6c3d61",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}

Please check the workflow logs.

[kingpanther13]

Will work on this after #960 merges, I want to work on both the web version and the text field/toggle in config settings in the same PR.

[github-actions]

🔍 Analysis

This issue is a well-reasoned enhancement request to provide a "middle ground" for stable addon users who want to opt into specific unstable features without switching to the riskier dev channel or manually tinkering with environment variables (which is difficult in the HA Supervisor environment).

Currently, features like ha_config_set_yaml are intentionally hidden from the stable addon's configuration UI to prevent accidental misuse by inexperienced users. However, as noted in the issue, this creates a barrier for advanced users on the stable channel. The proposed beta_features mechanism provides a generic, documented path (via docs/beta.md) to enable these capabilities.

The implementation involves adding a beta_features string field to the addon's configuration schema and updating the start.py script to parse this field and set the corresponding environment variables before the MCP server starts. This approach is highly compatible with the existing codebase and provides a scalable way to gate future experimental features.

🛠️ Suggested Steps

1. Update Addon Configuration: Add beta_features to both the options and schema sections in homeassistant-addon/config.yaml.
2. Modify Startup Script: Update homeassistant-addon/start.py to:
   • Read the beta_features string from /data/options.json.
   • Parse it as a comma-separated list.
   • Map known feature keys (e.g., yaml_config_editing, filesystem_tools) to their respective environment variables.
   • Set those environment variables using os.environ.
3. Update Documentation: Ensure docs/beta.md reflects this new opt-in method as the primary path for addon users.

📊 Technical Analysis (for maintainers)

Root Cause

The stable addon's config.yaml uses a strict schema that only exposes stable, well-tested toggles. Features gated by environment variables (like ENABLE_YAML_CONFIG_EDITING) are inaccessible to most addon users because the HA Supervisor does not allow setting arbitrary environment variables; it only passes options defined in the schema.

Affected Code

• homeassistant-addon/config.yaml - Needs schema update.
• homeassistant-addon/start.py - Needs parsing logic for the new beta_features option.
• src/ha_mcp/config.py - (Indirectly) receives the environment variables.

Proposed Fix

homeassistant-addon/config.yaml

options:
  # ... existing options ...
  beta_features: ""
schema:
  # ... existing schema ...
  beta_features: str?

homeassistant-addon/start.py

--- a/homeassistant-addon/start.py
+++ b/homeassistant-addon/start.py
@@ -155,6 +155,7 @@
     enable_skills_as_tools = True  # default
     enable_tool_search = False  # default
     enable_yaml_config_editing = False  # default
+    beta_features = ""  # default
     config_read_ok = True
 
     if config_file.exists():
@@ -171,6 +172,7 @@
             enable_tool_search = raw_tool_search if isinstance(raw_tool_search, bool) else False
             raw_yaml_config = config.get("enable_yaml_config_editing", False)
             enable_yaml_config_editing = raw_yaml_config if isinstance(raw_yaml_config, bool) else False
+            beta_features = config.get("beta_features", "")
         except Exception as e:
             log_error(f"Failed to read config: {e}, using defaults")
             config_read_ok = False
@@ -187,6 +189,17 @@
     # Generate or retrieve secret path
     secret_path = get_or_create_secret_path(data_dir, custom_secret_path)
 
+    # Parse beta features
+    if beta_features:
+        features = [f.strip().lower() for f in beta_features.split(",")]
+        if "yaml_config_editing" in features:
+            enable_yaml_config_editing = True
+            log_info("Beta feature enabled: yaml_config_editing")
+        if "filesystem_tools" in features:
+            os.environ["HAMCP_ENABLE_FILESYSTEM_TOOLS"] = "true"
+            log_info("Beta feature enabled: filesystem_tools")
+        # Add future beta mappings here
+
     log_info(f"Backup hint mode: {backup_hint}")
 
     # Set up environment for ha-mcp

Related Issues/PRs

• refactor(addon): move ha_config_set_yaml to dev channel only (breaking — stable toggle removed, set ENABLE_YAML_CONFIG_EDITING or use dev add-on) #942 - Establish docs/beta.md and move ha_config_set_yaml out of main UI.
• feat: web-based settings UI for per-tool enable/disable/pin #960 - Web UI integration (settings page).

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Superseded by #1164 — beta-features opt-in folded into the broader advanced-settings panel work alongside the stable-addon beta_features text field.