| name | haos-ssh-maintenance |
| description | Home Assistant OS SSH maintenance for config files, YAML, custom components, shell troubleshooting, or interactive ha CLI. |
HAOS SSH Maintenance
Use SSH only when API-based inspection is not enough.
Default posture
Prefer the Home Assistant API first for:
- entity state inspection
- history and logbook
- automation listing, enable/disable, and trigger
- service-level testing
Switch to SSH when:
- files under
/config need reading or editing
- YAML definitions must be inspected directly
custom_components must be inspected- shell-level troubleshooting is required
ha CLI work is needed
Use the SSH target stored in the workspace AGENTS.md ## Tools section.
Common HAOS paths
/config/config/configuration.yaml/config/automations.yaml/config/scripts.yaml/config/scenes.yaml/config/custom_components//config/home-assistant_v2.db
Logs
Do not assume Home Assistant writes logs to a file by default.
Check logs in this order:
- Home Assistant UI logs when the issue is visible there
- interactive
ha CLI log access such as ha core logs
- Supervisor or container-side logs when available
- file-based logs only if the environment explicitly enables them
Observed behavior for this environment:
ha core logs may fail in one-shot SSH modeha core logs works in an interactive PTY-backed SSH session
Workflow
- Decide whether the task is one-shot SSH or interactive SSH.
- Start read-only.
- Identify the smallest affected file or command path.
- Explain the intended change before risky edits.
- Edit minimally.
- Verify surrounding context after the change.
- Prefer reload over full restart when possible.
- Report exactly what changed.
Home Assistant YAML pitfalls
When editing Home Assistant automations or packages by hand:
- In automation YAML, use
service: to call a service such as shell_command.foo or light.turn_on.
- Do not write
action: shell_command.foo in YAML automations. That produces an unknown action error in this environment.
action is the UI/schema concept for a step in the actions list, but in hand-written YAML the concrete service call key should be service:.- After editing automation/package YAML, reload both core config and automations when possible, then validate by triggering the automation once.
SSH modes
One-shot SSH
Use one-shot SSH commands for:
- reading files under
/config
- grepping YAML or custom component code
- listing directories
- small targeted edits
- quick environment inspection
One-shot SSH is appropriate for commands like:
Do not assume ha CLI commands will work in one-shot mode.
Interactive SSH
Use an interactive PTY-backed SSH session for:
ha core logs- other
ha CLI commands that fail in one-shot mode
- shell flows that require a login session or interactive context
When running from OpenClaw, prefer a PTY-backed exec session and then send commands into the live SSH shell.
Investigation order
Automation problems
- API logbook and history
/config/automations.yaml/config/scripts.yaml- relevant Home Assistant or Supervisor logs
Naming or entity-origin confusion
- API-visible attributes and registry-derived metadata
- YAML definitions under
/config
- template, MQTT, REST, command_line, utility_meter, and custom component definitions
Integration or startup failures
- relevant Home Assistant or Supervisor logs
- referenced YAML blocks
custom_components if relevant
Change boundaries
Use SSH for:
- YAML edits
- package edits
custom_components inspection- interactive
ha CLI log inspection
- Supervisor or container-side log inspection
- shell-level checks
- targeted
.storage inspection or edits when UI/registry-backed state must be changed directly
Do not use SSH first for:
- normal state checks
- routine entity discovery
- simple automation enable/disable/trigger actions
.storage direct-edit policy
Home Assistant internal storage under /config/.storage/ can be edited when necessary, including files such as:
/config/.storage/core.entity_registry/config/.storage/core.device_registry/config/.storage/core.config_entries
Rules:
- Treat
.storage edits as a last-resort or targeted-operation path, not the default first move.
- Back up the exact file before every edit.
- Prefer the smallest possible change to a specific entity/device/config entry.
- Expect UI names to live in
core.entity_registry; YAML friendly_name overlays can override what the UI shows.
- Be aware of writeback/refresh timing: changes may not appear immediately and may require reload or restart.
- Avoid broad rewrites of
.storage JSON unless explicitly necessary.
- Report both the file path edited and the rollback path created.
Safety
- Read before editing.
- Change the smallest possible region.
- Avoid broad rewrites when a targeted edit is enough.
- Ask before changing behavior that affects locks, alarms, access control, or physical entry.
Reporting
When using this skill, report:
- what path was inspected
- what was found
- what changed, if anything
- whether reload or restart is needed
