Haos Ssh Maintenance

Perform Home Assistant OS maintenance via SSH for direct file access, YAML edits, custom component inspection, shell troubleshooting, and interactive ha CLI...

Security Scan

Instructions and requirements match the stated purpose (SSH-based Home Assistant OS maintenance); the skill is an instruction-only helper and does not request unrelated credentials or installs.

Purpose & Capability

The name/description (HAOS SSH maintenance) align with the SKILL.md: it documents when to use SSH, paths to inspect, and safe edit workflows. It does not ask for unrelated credentials, binaries, or system-level access beyond what SSH-based maintenance implies.

Instruction Scope

The runtime instructions explicitly allow reading and targeted editing of sensitive Home Assistant files (including files under /config and .storage). That behavior is coherent with the stated maintenance purpose, but these actions are inherently sensitive; the skill appropriately recommends backups and minimal edits. The SKILL.md references an SSH target stored in TOOLS.md — ensure that file exists and points to the intended host before use.

Install Mechanism

No install spec or code files are present (instruction-only). Nothing is written to disk by the skill itself, which is the lowest-risk install posture.

Credentials

The skill requests no environment variables, credentials, or config paths in the registry metadata. The operations it describes (SSH to HAOS, reading/editing /config) do require SSH access in practice, which is proportional to the described tasks.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request persistent presence or to modify other skills' configs. Autonomous invocation is allowed by default but not shown as elevated in the metadata.

Assessment

This skill is a coherent, instruction-only SSH maintenance guide for Home Assistant OS. Before using it: (1) ensure you trust the agent/skill and only provide SSH credentials to trusted code—SSH access grants full filesystem access; (2) verify the referenced TOOLS.md contains the correct SSH target so you don't connect to the wrong host; (3) follow the SKILL.md guidance exactly when editing .storage (always back up the exact file and make minimal, targeted edits); (4) prefer API-first checks when possible and use a PTY-backed interactive session for ha CLI commands; and (5) consider running edits manually or reviewing proposed commands before granting the agent permission to execute them.

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 TOOLS.md.

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:

1. Home Assistant UI logs when the issue is visible there
2. interactive ha CLI log access such as ha core logs
3. Supervisor or container-side logs when available
4. file-based logs only if the environment explicitly enables them

Observed behavior for this environment:

• ha core logs may fail in one-shot SSH mode
• ha core logs works in an interactive PTY-backed SSH session

Workflow

1. Decide whether the task is one-shot SSH or interactive SSH.
2. Start read-only.
3. Identify the smallest affected file or command path.
4. Explain the intended change before risky edits.
5. Edit minimally.
6. Verify surrounding context after the change.
7. Prefer reload over full restart when possible.
8. 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:

• cat
• grep
• sed
• find
• ls

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

1. API logbook and history
2. /config/automations.yaml
3. /config/scripts.yaml
4. relevant Home Assistant or Supervisor logs

Naming or entity-origin confusion

1. API-visible attributes and registry-derived metadata
2. YAML definitions under /config
3. template, MQTT, REST, command_line, utility_meter, and custom component definitions

Integration or startup failures

1. relevant Home Assistant or Supervisor logs
2. referenced YAML blocks
3. 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