hassio-addons/claude_desktop

Home assistant add-on: Claude Desktop

Run Claude Desktop in a LinuxServer.io Selkies add-on, with Headroom MCP context compression, RTK Bash-output acceleration, and code-intelligence tooling wired in by default.

Installation

1. Add this repository to the Home Assistant add-on store.
2. Install Claude Desktop.
3. Start the add-on and open the web UI from the sidebar.
4. Sign in with your Claude account from the Desktop app.

Claude Desktop sign-in requires a claude.ai plan that supports the Desktop app. API keys are not accepted by the Desktop application. Anthropic's Linux beta currently does not include Computer Use or dictation.

Architecture

Everything is built around the Claude Desktop app. Claude Code is installed in the same image but is not exposed as a standalone service: Claude Desktop's cowork and dispatch sessions run it internally, and they pick up the shared Claude Code configuration (~/.claude), hooks, and MCP servers automatically.

• Claude Desktop uses Headroom through its MCP tools.
• Claude Code sessions inside Desktop get the same MCP servers via ~/.claude.json and RTK's PreToolUse Bash hook via ~/.claude/settings.json.
• gnome-keyring provides the Secret Service backend Electron needs to persist sign-in and dispatch permission grants across restarts.

Features

• Claude Desktop in single-app Selkies mode with Home Assistant ingress.
• Official Claude Code stable package powering Desktop cowork/dispatch sessions.
• Persistent $HOME at the configured data_location (default /data/data), preserving Desktop and Claude Code state across restarts.
• Persistent sign-in through a bundled, auto-unlocked gnome-keyring.
• Optional runtime Claude Desktop updates from Anthropic's apt repository.
• Optional extra apt and pip package installation (pip installs use uv for speed).
• Baked-in git, GitHub CLI (gh), and ripgrep.
• Custom script support through the repository standard claude_desktop.sh.
• Bundled optimization tools: Headroom (MCP + local proxy), RTK, tokensave, and Caveman — each individually switchable.
• Optional Home Assistant MCP bridge so Claude can query and control Home Assistant.
• Headroom dashboard exposed on mapped port 8787.
• Low-power defaults for GPU mapping, Selkies frame rate, and volatile caches.

Options

Option	Default	Description
PUID / PGID	0 / 0	Numeric user and group applied by the LinuxServer initialization.
TZ		Optional timezone, for example Europe/Brussels.
KEYBOARD		Optional Selkies keyboard layout.
PASSWORD		Optional password for direct Selkies ports.
DRINODE		Optional GPU device override for Selkies.
DNS_server	8.8.8.8	DNS server used by the standard DNS module.
auto_update	true	Upgrade claude-desktop from Anthropic's apt repository at startup.
install_headroom	true	Register the Headroom MCP server and run the supervised local proxy/dashboard.
install_rtk	true	Configure RTK's Claude Code PreToolUse hook.
install_tokensave	true	Register the tokensave code-intelligence MCP server for Desktop and Claude Code.
install_caveman	true	Install the Caveman Claude Code plugin in the persistent Claude home.
install_github_cli	true	Enable setup checks for the baked-in git and gh commands.
github_token		Optional GitHub token used to authenticate gh and Git operations.
github_username		Optional global Git author name.
github_email		Optional global Git author email.
enable_ha_mcp	false	Register Home Assistant's MCP server in Claude (requires ha_mcp_token).
ha_mcp_url	http://homeassistant:8123/mcp_server/sse	SSE endpoint of Home Assistant's MCP Server integration.
ha_mcp_token		Home Assistant long-lived access token used by the MCP bridge.
additional_apps		Comma-separated Debian apt packages to install at startup.
additional_pip		Comma-separated pip packages installed at startup (via uv).
data_location	/data/data	Persistent home directory for Claude and tooling.
env_vars	[]	Additional environment variables exported inside the container.

Headroom behavior

When install_headroom is enabled, the add-on registers headroom mcp serve in Claude Desktop and Claude Code, and starts a supervised local Headroom backend. Claude can use headroom_compress, headroom_retrieve, and headroom_stats through MCP.

Claude Desktop overrides ANTHROPIC_BASE_URL, so it is deliberately launched without proxy injection; the MCP integration is the supported path.

The Headroom dashboard is available at:

http://<home-assistant-host>:8787/dashboard

through the default 8787/tcp port mapping. The dashboard is unauthenticated and is reachable wherever Home Assistant publishes that port, so treat it as sensitive: do not expose it directly to the public internet, and unmap the port in the add-on Network section if you do not want it reachable at all.

Home Assistant MCP bridge

To let Claude query and control Home Assistant:

1. In Home Assistant, add the Model Context Protocol Server integration (Settings → Devices & services → Add integration).
2. Create a long-lived access token (your profile → Security).
3. Set enable_ha_mcp: true and paste the token into ha_mcp_token in the add-on configuration, then restart the add-on.

The add-on bridges Claude to the integration's stateless Streamable HTTP endpoint (/api/mcp) with mcp-proxy. Override ha_mcp_url only if your Home Assistant instance is not reachable as homeassistant:8123 from add-ons.

Custom scripts

The add-on includes the repository standard custom-script executor. On first start, it seeds claude_desktop.sh in the add-on config directory. Commands in that script run during startup, allowing local customization without rebuilding the image.

Data and cache locations

Persistent state is stored in the configured data_location (default /data/data):

• Claude Desktop sign-in: ~/.config/Claude (token encrypted via gnome-keyring; keyring DB in ~/.local/share/keyrings)
• Claude Code settings, hooks, sessions, and plugins: ~/.claude
• Headroom, RTK, and tokensave user state: their standard paths below the shared home

Volatile cache data is redirected to /tmp/cache through $XDG_CACHE_HOME and $HOME/.cache.