fix: survive read-only filesystems at startup

[kingpanther13]

What does this PR do?

Fixes #1125 — ghcr.io/homeassistant-ai/ha-mcp:latest crashes at startup
under hardened Docker setups (read_only: true, user: 1000:1000,
tmpfs: /tmp):

OSError: [Errno 30] Read-only file system: '/.ha-mcp'
  in _get_config_path() → home_dir.mkdir(parents=True, exist_ok=True)

Two contributing factors:

1. The Dockerfile didn't set ENV HOME, so under USER mcpuser Docker
   left HOME=/ (moby/moby#2968).
   Path.home() resolved to /, ha-mcp tried to mkdir /.ha-mcp, and
   read_only: true made that fatal. Even on writable filesystems this
   silently polluted the container's filesystem root with a /.ha-mcp/
   directory.
2. _get_config_path() (added in feat: web-based settings UI for per-tool enable/disable/pin #960) unconditionally mkdirs the
   home dir on every server start, with no fallback.

Coordinated changes

Shared resolver (src/ha_mcp/utils/data_paths.py, new):
single source of truth for "where does ha-mcp write its persistent files".

#	Source	Used for
1	HA_MCP_CONFIG_DIR env var	Hardened Docker bind-mount override
2	/data (when SUPERVISOR_TOKEN set)	Home Assistant add-on persistent dir
3	~/.ha-mcp	Standard install
4	<tempdir>/ha-mcp	Last-resort fallback (server still runs, no persistence)

The resolved dir is memoized at module level so the fallback warning
emits once at startup instead of on every save/load HTTP request.

settings_ui:

• _get_config_path becomes a thin get_data_dir() / "tool_config.json" wrapper.
• load_tool_config replaces the path.exists() + read_text() two-step with a single try: read_text() except OSError:. Path.exists() only swallows ENOENT/ENOTDIR/EBADF/ELOOP, so EACCES (e.g. HA_MCP_CONFIG_DIR pointing at an existing 0700 dir owned by another UID) would re-introduce the same class of crash. Confirmed empirically: errno=13 propagates from pathlib.Path.exists().
• save_tool_config now returns bool, and the _save_tools HTTP route returns 500 when the write fails. The JS already handles !resp.ok with "Save failed!" — it was never given the chance.

utils/usage_logger: switch the default log path from Path.home() / ".ha-mcp" / "logs" to get_data_dir() / "logs". Logs now follow the same precedence as the tool config — HA_MCP_CONFIG_DIR works for them too, and add-on mode lands in /data/logs/ (the supervisor's persistent location, was previously ephemeral ~/.ha-mcp/logs/).

Dockerfile:

• ENV HOME=/home/mcpuser so Path.home() resolves correctly under the default user.
• chmod 0755 /home/mcpuser because the base image's /etc/login.defs sets HOME_MODE=0700; that's fine when the container runs as mcpuser, but un-traversable when users override --user UID:GID (the issue reporter does so) — anything that stats a path under HOME then raises PermissionError. Mode 0755 keeps write access restricted to mcpuser.

Tests

File	Class	What it pins
test_data_paths.py (new)	TestPriorityOrder	HA_MCP_CONFIG_DIR > /data > ~/.ha-mcp
	TestFallbacks	Issue #1125 regression; HA_MCP_CONFIG_DIR mkdir-fail chains to tmpdir
	TestMemoization	Single warning per startup; resolver re-runs when cache cleared
test_settings_ui.py	TestConfigPath	Wrapper sanity; load_tool_config doesn't crash on EACCES (same-class regression guard)
	TestSaveToolConfig (new)	bool return contract
	TestSaveToolsValidation	500 surfaced when save fails
test_usage_logger.py	TestUsageLoggerDefaults	Honors HA_MCP_CONFIG_DIR

Full unit suite: 1684 passed, 1 skipped (numpy not installed, unrelated). ruff check clean. mypy src/ clean.

Local Docker verification

Built locally and confirmed three real scenarios:

Scenario	Before	After
Reporter's compose: --read-only --user 1000:1000 --tmpfs /tmp	crash	runs (config falls back to /tmp/ha-mcp/)
Default user (no overrides)	"works" but creates /.ha-mcp 🚨	works (creates ~/.ha-mcp)
HA_MCP_CONFIG_DIR=/data/ha-mcp with bind-mount + read-only	n/a	runs, settings + logs persist to bind-mount

In all "after" cases the FastMCP banner displays and uvicorn binds http://0.0.0.0:8086. The original stack trace from #1125 no longer reproduces.

Release note

Users who ran :latest between #960 (2026-05-02) and this fix and had a writable / (default Docker, no read_only: true) will have had their settings UI tool config silently written to /.ha-mcp/tool_config.json at the filesystem root, because Docker leaves HOME=/ under USER mcpuser without an explicit ENV HOME (moby/moby#2968). After this fix the resolver writes to ~/.ha-mcp (or HA_MCP_CONFIG_DIR / /data when applicable) and no code path reads from /.ha-mcp/ — any per-tool enable/disable/pin choices made on broken :latest need to be recreated in the settings UI after upgrading. (Users who hit the actual #1125 crash had nothing persisted, so nothing to migrate.)

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest) — 1684 passed, 1 skipped
• Code follows style guidelines (uv run ruff check) — and mypy src/ clean

Checklist

• I have updated documentation if needed — HA_MCP_CONFIG_DIR is documented in the resolver's docstring; happy to surface it in README.md or the setup wizard if you'd like.

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses startup crashes occurring in hardened Docker environments where the filesystem is read-only or the home directory is not writable. By improving how the application locates its configuration file and adjusting Docker container defaults, the service is now more robust and flexible for various deployment configurations.

Highlights

• Configuration Path Resilience: Updated _get_config_path to handle read-only filesystems by falling back to a temporary directory and introducing an HA_MCP_CONFIG_DIR environment variable for explicit overrides.
• Docker Environment Improvements: Explicitly set HOME in the Dockerfile to prevent path resolution issues and updated home directory permissions to 0755 to support non-root user UID/GID overrides.
• Testing: Added three new unit tests to verify configuration path precedence, fallback behavior on read-only filesystems, and regression protection for startup crashes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request improves the robustness of the MCP server when running in restricted environments, such as read-only Docker containers. Key changes include setting the HOME environment variable explicitly in the Dockerfile, adjusting home directory permissions to 0755, and implementing a fallback mechanism to a temporary directory for the tool configuration when the home directory is unwritable. Additionally, a new HA_MCP_CONFIG_DIR environment variable allows for explicit configuration path overrides. The feedback suggests refining the fallback logic to improve debuggability by including specific operation context in log messages and ensuring the operation context is initialized before fallible actions.

[kingpanther13]

Review pass complete (force-pushed 5024a43)

Ran the PR review toolkit (code-reviewer, pr-test-analyzer, comment-analyzer, silent-failure-hunter) plus addressed Gemini's inline suggestion. Findings I confirmed empirically and fixed:

Finding	Source	Status
load_tool_config() path.exists() propagates PermissionError (EACCES not in pathlib._IGNORED_ERRNOS) — same class as the original #1125 bug	silent-failure-hunter	Fixed: replaced exists()+read_text() two-step with single try: read_text() except OSError:
HA_MCP_CONFIG_DIR set-but-unwritable returned a broken path; every save then OSError'd in save_tool_config	code-reviewer + pr-test-analyzer + silent-failure-hunter	Fixed: HA_MCP_CONFIG_DIR mkdir failure now chains into the tmpdir fallback (consistent with home-dir branch)
Warning emitted on every _get_config_path() call (called from each settings UI HTTP request) → log spam	silent-failure-hunter	Fixed: result memoized in module-level _CONFIG_PATH_CACHE; warning emits once at startup
Double warning when home AND tmpdir both fail; second one misleadingly says "Falling back to ..."	Gemini + silent-failure-hunter	Fixed: single warning per resolution, message branches on fallback mkdir success
~50% of original diff was unrelated ruff format reflows on untouched code	code-reviewer	Reverted: restored settings_ui.py from origin/master and re-applied only the targeted fix; diff is now focused (87 added / 11 removed in settings_ui.py, vs. 152/38 before)
Dockerfile chmod comment framing about useradd default 0700 was image-specific; comment-analyzer also flagged "Path.home() raises PermissionError" being technically inaccurate (traversal raises, not Path.home() itself)	code-reviewer + comment-analyzer	Reworded: comment now references /etc/login.defs HOME_MODE and "stats a path under HOME" rather than Path.home()

Confirmed but deliberately deferred (out of PR scope)

• usage_logger.py:120-127 already uses try/except OSError but its logger.exception on save failures will now write to a same-class fallback path (i.e. /home/mcpuser/.ha-mcp/logs/) that's unwritable for --user UID:GID users; should adopt the same memoized-resolution + tempdir-fallback pattern in a follow-up.
• save_tool_config returns None on OSError and the HTTP handler reports success: True to the browser — this is a UX bug (user thinks save worked), but predates this PR and has its own scope.
• Test edge case (both home AND tmpdir unwritable) — defensive-only, low priority; left as a possible follow-up.

Tests

5 unit tests in TestConfigPath (all in tests/src/unit/test_settings_ui.py):

• test_ha_mcp_config_dir_overrides_supervisor_token — env var precedence
• test_falls_back_to_tmpdir_when_home_unwritable — issue #1125 regression
• test_ha_mcp_config_dir_unwritable_chains_to_tmpdir — new fallback chaining
• test_load_tool_config_does_not_crash_on_unreadable_config_dir — same-class follow-up regression
• test_warning_emitted_only_once_via_module_cache — log-spam guard

Full unit suite: 1679 passed, 1 skipped (numpy unrelated). ruff check src/ tests/ homeassistant-addon/ homeassistant-addon-webhook-proxy/ scripts/ clean. mypy src/ clean.

Re-verified the three Docker scenarios (reporter's compose, default user, HA_MCP_CONFIG_DIR bind-mount) — all start cleanly under :fix-1125 build.

[kingpanther13]

Follow-ups addressed (force-pushed 8f8efc0)

Pulled in the items I'd previously marked deferred:

Concern	Source	Fix
usage_logger.py had the same root cause but wasn't patched (would silently fall back to Path.home()/... and ignore HA_MCP_CONFIG_DIR)	code-reviewer issue #1	Extracted shared resolver to new utils/data_paths.py; both settings_ui and usage_logger now go through get_data_dir(). Add-on mode now lands logs in /data/logs/ (the supervisor's persistent dir) instead of ephemeral ~/.ha-mcp/logs/.
save_tool_config swallowed OSError and _save_tools returned {success: true} while the user's change was lost	silent-failure-hunter issue #4	save_tool_config now returns bool; _save_tools returns 500 with a structured error body when it fails. The JS at saveConfig() already shows "Save failed!" on !resp.ok — it just wasn't being given the chance.
Mixed import and from … import in test fixture	github-code-quality bot	Replaced import ha_mcp.settings_ui as su + manual reset with monkeypatch.setattr("ha_mcp.utils.data_paths._DATA_DIR_CACHE", None) — also gives proper between-test isolation via monkeypatch's auto-restore. Thread resolved.
PR title was vague	user feedback	Renamed: fix: tolerate read-only filesystem when locating tool config → fix: survive read-only filesystems at startup.

New tests (9 total across new + existing files):

• test_data_paths.py: priority order, both fallback branches, memoization (single-warning guard), uncached resolver re-runs.
• test_settings_ui.py: save_tool_config bool contract (success + OSError → False); _save_tools returns 500 when save fails.
• test_usage_logger.py: default path uses shared resolver; HA_MCP_CONFIG_DIR redirects logs.

Full unit suite: 1684 passed, 1 skipped. ruff check src/ tests/ ... clean. mypy src/ clean. Re-verified the three Docker scenarios under the new build.

[kingpanther13]

Implementation Summary

Choices Made:

• Extracted a shared resolver to a new utils/data_paths.py rather than duplicating fallback logic in settings_ui and usage_logger. Both modules now route through get_data_dir(), so HA_MCP_CONFIG_DIR and add-on /data mode work identically for tool config and logs.
• 4-tier precedence: HA_MCP_CONFIG_DIR env → /data (when SUPERVISOR_TOKEN is set) → ~/.ha-mcp → <tempdir>/ha-mcp last-resort. The server keeps running even when nothing is writable; only persistence is lost.
• Memoized result in a module-level _DATA_DIR_CACHE so the fallback warning emits once at startup instead of on every settings-UI HTTP request.
• Replaced path.exists() + read_text() in load_tool_config with a single try: read_text() except OSError:. Path.exists() only swallows ENOENT/ENOTDIR/EBADF/ELOOP; EACCES propagates and would re-introduce the same class of crash as Updating to :latest (dev) is failing #1125.
• save_tool_config now returns bool; _save_tools returns 500 with a structured error body on failure. The JS at saveConfig() already had a !resp.ok → "Save failed!" branch — it just wasn't being given the chance.
• Dockerfile: explicit ENV HOME=/home/mcpuser (otherwise Docker leaves HOME=/ under non-root users — Set $HOME in container moby/moby#2968) and chmod 0755 /home/mcpuser so users overriding --user UID:GID can still stat paths under HOME without PermissionError. Mode 0755 keeps writes restricted to mcpuser.

Problems Encountered:

• Initial fix introduced a same-class regression: load_tool_config()'s path.exists() would still propagate PermissionError on an unreadable config dir. Caught by silent-failure-hunter and pinned with test_load_tool_config_does_not_crash_on_unreadable_config_dir.
• HA_MCP_CONFIG_DIR set-but-unwritable returned a broken path; every save then OSError'd. Chained the env-var branch into the same tmpdir fallback as the home-dir branch (test_ha_mcp_config_dir_unwritable_chains_to_tmpdir).
• usage_logger.py had the same root cause but wasn't part of the original fix — it would silently fall back to Path.home()/.ha-mcp/logs/ and ignore HA_MCP_CONFIG_DIR. Initially deferred, then pulled in once the shared resolver existed.
• Original diff accidentally bundled ~50% unrelated ruff format reflows on untouched code. Reverted settings_ui.py to origin/master and re-applied only the targeted fix; settings_ui diff dropped from 152/38 to 87/11.
• Comment rot: Dockerfile comment cited useradd defaults (image-specific) and said Path.home() raises PermissionError (technically the traversal raises, not Path.home() itself). Reworded to reference /etc/login.defs HOME_MODE and "stats a path under HOME". Caught by comment-analyzer.
• A test fixture mixed import ha_mcp.settings_ui as su + manual cache reset. Replaced with monkeypatch.setattr("ha_mcp.utils.data_paths._DATA_DIR_CACHE", None) so test isolation comes from monkeypatch's auto-restore rather than ad-hoc teardown.

Verification:

• Full unit suite: 1684 passed, 1 skipped (numpy unrelated). ruff check clean. mypy src/ clean. All PR Validation Pipeline checks green.
• Local Docker: reporter's --read-only --user 1000:1000 --tmpfs /tmp compose, default-user, and HA_MCP_CONFIG_DIR bind-mount scenarios all start cleanly under :fix-1125. Original Updating to :latest (dev) is failing #1125 stack trace no longer reproduces.

[Patch76]

Re-review of HEAD d66c651a. The fix closes #1125. ENV HOME, the EACCES handling in load_tool_config, and the shared data_paths.get_data_dir() resolver are all correct. Test coverage — including the real chmod 0o000 regression guard at tests/src/unit/test_settings_ui.py:198 — is solid.

Three sticking points before squash:

• One residual same-class bug: the addon-mode branch at data_paths.py:70-71 returns Path("/data") without verifying writability and silently overrides an explicit HA_MCP_CONFIG_DIR if its mkdir failed.
• One env-var edge case: HA_MCP_CONFIG_DIR=" " (whitespace) is truthy, mkdirs a three-space-named directory under cwd. Path(" ").absolute() empirically resolves cwd-relative.
• The PR title — auto-merge is queued, so the squash subject inherits fix: fix read-only filesystems /:latest at startup ( fixes #1125) verbatim into master history the moment the next approval lands. git log upstream/master --grep="^fix: fix " returns nothing else; this would be the first double-verb fix subject, alongside the /:latest typo and the leading space inside the parens. Worth editing before approving.

For existing :latest users who hit the original bug, data was previously written to /.ha-mcp/ (filesystem root, from HOME=/); after this fix no code path reads from there. Worth a one-line release note.

Findings inline.

[kingpanther13]

Patch76's review addressed in befcd9a

All five inline findings + the title.

Finding	Fix
Addon branch returns Path("/data") without writability check; silently discards HA_MCP_CONFIG_DIR override on env-var mkdir failure	mkdir-then-check; on success returns /data only when preferred is None (failed override falls through to tmpdir); on failure sets preferred = /data and continues into the home/tmpdir chain
HA_MCP_CONFIG_DIR=" " is truthy → mkdir's a literal whitespace-named dir under cwd	os.environ.get("HA_MCP_CONFIG_DIR", "").strip()
Docstring "warning emits once" overclaims under concurrent first-access	Weakened: now flags lru_cache doesn't serialize the wrapped call when empty; idempotent mkdir, cosmetic-only double warning
Last-resort branch logged at WARNING when persistence is silently disabled	Upgraded to logger.error
No test for env-fail + SUPERVISOR_TOKEN-set interaction	Added test_ha_mcp_config_dir_unwritable_in_addon_mode_chains_to_tmpdir (silent-override-discard regression) and test_falls_back_when_addon_data_dir_unwritable (residual same-class bug)
PR title double-verb / /:latest typo / stray space	Renamed to fix: survive read-only filesystems at startup

Existing test_addon_path_when_supervisor_token_set updated to stub Path.mkdir for /data (the new writability check would otherwise hit the real path on dev/CI machines). test_returns_unwritable_tmpdir_when_everything_fails now asserts levelno == logging.ERROR.

For existing :latest users who hit the original bug, data was previously written to /.ha-mcp/ (filesystem root, from HOME=/); after this fix no code path reads from there. Worth a one-line release note.

Good call — that's a stranded-data note worth surfacing, and we already have the conventional-commit body to drive a release note. I'll add it to the PR description rather than the commit (the description is what the addon CHANGELOG sync uses).

[Patch76]

Round 2: all 5 inline findings verified fixed in befcd9a. CI green (17 pass / 2 skipping for hotfix-origin and dependabot). Per-thread verifications posted as replies above; threads already resolved.

Two unrelated observations for before-approval:

High — auto_merge.commit_title is cached at enable-time and ships at squash time:

.title:                    "fix: survive read-only filesystems at startup"           (clean)
.auto_merge.commit_title:  "fix: fix read-only filesystems /:latest at startup ( fixes #1125) (#1138)"  (cached)

The PR title rename did not refresh the auto-merge cache. GitHub Community Discussion #16271 reproduces that the cached value is what lands on master at squash time, not the live .title. Either disable + re-enable auto-merge to refresh, or use gh pr merge 1138 --squash --subject "..." for manual merge. Otherwise the squash commit on master will carry fix: fix, /:latest, and the leading space inside the parens.

Low — cosmetic double-warning on the env-fail + addon-set + /data-unwritable trace (src/ha_mcp/utils/data_paths.py:82-87): user sees both HA_MCP_CONFIG_DIR=... could not be prepared and /data is not writable in add-on mode warnings, even though the env-fail short-circuit already determined the outcome (the override would have won). Cosmetic only — no functional issue, and a guard would complicate the flow disproportionately.

[Patch76]

Verified befcd9a against the Round-2 review above — all 5 inline fixes land cleanly, CI green on required checks. Auto-merge disabled to prevent the cached typo squash-subject from shipping; merge timing and subject are yours to control.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.