Preface¶
For people writing agent workflows for DSH (DeepSeek Harness), there is a common question they need to answer: can a specific session see Home Assistant (HA) at home? Where is HA running, what version is it, and what is its current status? The common practice is to write the address and token into documentation, or ask the user to report it every time a session starts. dsh-home-assistant-panel consolidates this into a one-time configuration: fill in the address, token, and 1–6 observables in the settings page, and the plugin will inject the environment baseline into the system prompt, providing a read-only ha_status tool and a real-time status card.
Below is an introduction to this plugin. The documentation is based on the GitHub README.
What is it¶
dsh-home-assistant-panel is a client-side plugin written by maintainer hotkong for DeepSeek Harness. Its positioning is read-only: it injects Home Assistant’s address, version, running status, and a few observables into the system prompt, so every new session starts knowing where HA is, what version it is, and its status, without needing to read documentation or copy tokens. It does not perform device control, does not modify configuration, and does not check logs.
The injection block appears in the system prompt for every request, approximately 150–300 tokens, looking like:
<home_assistant label="Living Room HA" url="http://homeassistant.local:8123">
Core 2026.10.4 | Supervisor 2026.10.4 | OS 18.3.1
Status: RUNNING (recovery_mode=false, watchdog=true)
Scale: 42 entities / 7 devices / 3 areas / 5 integrations
Disk: 13.8/27.7 GB used
Stats: 3 lights on | Indoor temp 22.0 °C | 1 person home
Notes: Restart takes about 4.5–5 mins; YAML config files no API, control via HA native interface
Update: 2026-11-04 16:34 (+08:00)
</home_assistant>
Configuration resides in the profile and is shared by all workspaces, so changing a workspace takes effect immediately.
Core Features¶
The plugin registers four entry points with a clear division of labor.
- Left Main Panel. Home Assistant in the left navigation opens a read-only status overview: version, running status, scale, disk, timezone, all observables, update time, refresh, and open HA. The configuration entry is hinted at in the settings page.
- Right Sidebar Quick View. Add Home Assistant in the right sidebar “+/Guide”, displaying status points, Core/Supervisor versions, running status, entity scale, max 3 observables, and update time; refreshes every 30 seconds, pauses when hidden, and can click “Refresh” to force a probe or “Open” to jump to the HA instance.
- Configuration Page. Located at Settings → Home Assistant, with the full status card at the top and the configuration form below.
- Agent Side. Directly asking “Check HA status” calls
ha_status; the system prompt already contains the environment block, so asking “how many lights are on at home” can also be answered.
The registration mechanisms for each entry differ: the settings page is registered in settings.section, the left main panel in sidebar.panellist + main, and the right sidebar in the official sidebarRightTabs + sidebar.right.pane.tab. If the host lacks the corresponding service, this entry silently skips, while other entries remain unaffected by ha_status; without configForms, the form degrades to a read-only hint.
Browser notifications are an independent switch, defaulting to off, and only notify when HA is unavailable or has recovered, without listening to device events. The first load only records the baseline and will not pop up immediately; it is only deemed DOWN after a continuous failureThreshold (default 2) failures. Permissions must be applied by clicking “Enable Browser Notifications” in the settings page, and a test notification can be sent; the notification requires the DSH page to stay open.
Installation and Enablement¶
Installation commands come from the original README:
dsh plugin --profile web add dsh-home-assistant-panel
After installing, refresh the page or restart dsh web. The plugin’s name in the market is dsh-home-assistant-panel.
If there is no “Home Assistant” entry in Settings, first check if it has been added to bundles:
dsh --profile web --dump-config | grep home-assistant
The absence of this line means the plugin has not been added to dsh.profile.bundles, and installing it into node_modules alone is not enough.
When developing locally, you can link: the repository into the profile’s dependencies and add the package name to dsh.profile.bundles; the plugin’s built-in cordis.patch.yml automatically inserts the home-assistant line, and the profile patch only needs to override config. The README mentions running locally this way, and the verification record is in the repository’s openspec/changes/0001-dsh-ha-plugin/tasks.md.
Typical Usage¶
After installing, configure it first. Open Settings → Home Assistant, the top is the status card, below is the configuration form, with fields including instance address, display name, notes, access token, observables, whether to inject prompts, inject workspace whitelist, and whether to count scale. Clicking “Save Config” or “Save Token” takes effect immediately, no restart required.
For the access token, it is recommended to use the UI: paste the long-term token in the settings page and click “Save Token”. It writes to $DSH_HOME/.credentials.yaml HA_TOKEN via the host credential service, and will not enter profile configuration, logs, or market backups; there is a “Clear” button next to it. The page will display the current parsed result, such as credential:HA_TOKEN or Token not found.
For manual scenarios, you can maintain the credential file yourself, with permissions required to be 0600:
version: 1
refs:
HA_TOKEN: <your long-term access token>
Inlining token directly in the profile YAML is a fallback solution and is not recommended: the token will be in plaintext in cordis.patch.yml and will enter backups of “included config files”.
Observables are written under stats, 1–6 of them, choose one of the two ways:
stats:
# 1) Entity shortcut (no admin token required)
- title: Indoor Temperature
entity: sensor.living_room_temperature
unit: " °C"
# 2) Jinja template (requires admin token; can perform aggregation)
- title: Lights On
template: "{{ states.light | selectattr('state','eq','on') | list | count }}"
The entity shortcut can optionally use attribute to read a specific attribute; a single item failure only displays — and does not affect other items. Templates can only come from configuration; tool parameters do not accept templates—the HA template interface can read the whole house status but cannot expose it to runtime parameters.
After configuration is complete, you can directly ask about HA status in the session or ask it to read the observables. The quick view card in the right sidebar auto-refreshes every 30 seconds and is suitable for keeping it open on the page.
Applicable Scenarios and Notes¶
It is suitable for developers or home users who want to hand over the HA environment to DSH sessions once and only care about the status. If you need to control devices, modify configuration, restart, check logs, edit automations, backup, or read YAML, you should switch to the HA native interface or the HA official MCP Server; dsh-home-assistant-panel intentionally does not do these. v0.1 also does not support multiple instances; use different profiles if you need multiple HAs.
Regarding security, the probe only sends read-only requests and never modifies HA; the token is replaced with *** in logs, the injection block, status card, and browser; the injection block is a read-only cache during system prompt assembly and waits for the network, so HA hanging will not stall the conversation. Please keep the credential file with 0600 permissions.
By the DSH plugin mechanism, the plugin runs with the permissions of the current dsh process. You should review the source code before installing to confirm that the patches and dependencies meet expectations. This plugin depends on @deepseek-ai/cordis and @deepseek-ai/schemastery (peerDependencies, both optional), and engines.dsh requires >=0.2.1-rc.1 <0.3.0-0.
Several common troubleshooting starting points:
| Symptom | Check First |
|---|---|
| No “Home Assistant” in Settings | dsh --profile web --dump-config | grep home-assistant; no line = not added to dsh.profile.bundles |
| Page exists but form shows “No config namespace” | Config not loaded: @deepseek-ai/schemastery parse failed; link: install needs to link plugin’s own node_modules |
| Click save is rejected / no response | Fields must be under volatile(); check settings/mutate error info in browser network |
| First prompt after restart says “No token” | Credential service not ready startup race; plugin uses 5 sec short TTL for “no credential” failure, wait a bit to self-heal |
| Status always unreachable | curl '<baseUrl>/api/' -H "Authorization: Bearer $HA_TOKEN"; then try GET /dsh-home-assistant/status?refresh=1 |
Plugin version is 0.1.0, license MIT.
Conclusion¶
The value of dsh-home-assistant-panel is to consolidate the HA environment configuration in one place: configure once, and then every new session starts knowing where HA is, what version, and its status, while retaining the read-only status card and ha_status tool. If the session only needs “to know”, it is sufficient; if it needs “to operate”, please use the HA native interface or the HA official MCP Server.
- Directory: https://www.skillhub.cn/plugins/hotkong/dsh-home-assistant-panel
- GitHub: https://github.com/hotkong/dsh-home-assistant-panel
