Terminal & SSH Addon - Home Assistant Guide

Using the Terminal & SSH Add-on in Home Assistant

The Terminal & SSH add-on lets you control Home Assistant using text commands. It opens a Linux shell (a text interface) either inside your browser (the web terminal) or via an SSH client ("Secure Shell", an app for remote access). This add-on is ideal for diagnostics, safe file management, backups, and maintenance - especially when you can't access the normal UI.

Note: The add-on runs inside Home Assistant's container, so it doesn't expose full host-level tools like docker or journalctl. However, it fully supports the ha command-line interface and basic Linux file utilities, making it safe and powerful for most everyday tasks.

What Does the Terminal & SSH Add-on Do?

When installed, you get two ways to access Home Assistant:

Web Terminal: Opens directly in your Home Assistant sidebar - no setup needed.
SSH Access: Connect from another device using an SSH app (e.g., PuTTY on Windows, Termius on mobile, or the built-in ssh command on macOS/Linux). All connections are encrypted for security.

A Linux shell is simply a text-based window where you type commands instead of clicking buttons. It may look intimidating, but most commands are short and easy to remember - and learning them gives you much more control over your system.

Installing the Terminal & SSH Add-on

Go to Settings > Add-ons > Add-on Store.
Search for "Terminal & SSH" and click it.
Click Install, then enable Start on boot and Show in sidebar.
Click Start. A new Terminal link will appear in your sidebar.

Click it to open the terminal and try a simple command like ha info or ls.

Enable SSH Access (Optional)

SSH lets you connect to Home Assistant from another device, not just the web terminal.

Authorized Keys (Recommended): Create an SSH key pair (two linked files that prove your identity securely). You can make these with ssh-keygen (macOS/Linux) or PuTTYgen (Windows). Paste your public key into the add-on configuration.
Password: A simpler but less secure option - fine for local network use.

Then connect using:

ssh root@homeassistant.local -p 22

What Works in the Add-on Shell

The add-on is designed for Home Assistant management and safe file operations. You can run:

Home Assistant CLI commands:

ha info
ha core logs
ha core check
ha core restart
ha supervisor logs

Manage backups from the command line:

If you're running Home Assistant OS, you can create or restore backups (also called snapshots) directly from here:

ha backups list            # List all backups and their slugnames
ha backups new --name "My Backup"    # Create a new backup
ha backups restore slugname          # Restore a specific backup

Update Home Assistant to a specific version:
```
ha core update --version 2025.11.0
```
(Replace 2025.11.0 with your desired version.)

File management in /config:

ls
cd /config
cat configuration.yaml
nano configuration.yaml

Basic system utilities:
- cp - Copy a file (duplicate it)
  cp configuration.yaml backup.yaml
- mv - Move or rename a file
  mv old.yaml new.yaml
- rm - Delete a file
  rm test.yaml
- grep - Search inside files
  grep light configuration.yaml
- tail -f - Watch a file live (useful for logs)
  tail -f home-assistant.log
- less - View long text files page by page
  less home-assistant.log

Unavailable here: Full host tools like journalctl or docker - those require host-level access.

Basic Commands & Syntax (Beginner Cheat Sheet)

Here are the core commands you'll use most often, with explanations:

ls - Lists files in the current folder.
cd - "Change directory." Example: cd /config
pwd - Shows your current folder ("where am I?").
cat filename - Prints a file's contents.
nano filename - Opens a text editor. Press Ctrl+O to save, Ctrl+X to exit.
mkdir newfolder - Makes a new folder.
rm filename - Deletes a file (no undo).
clear - Clears the screen.
exit - Closes the terminal session.

Most commands follow this pattern: command [options] [filename or path]
Example: cp source.yaml /config/backup.yaml

Real-World Use Cases

Many of these actions can also be done through the Home Assistant UI - the terminal simply provides an alternative method, especially useful if the UI is unresponsive or you prefer command-line speed.

Check configuration before restarting:
ha core check
View detailed logs:
ha core logs
Create or restore a backup quickly:
ha backups new --name "Before Update"
Update to a specific Home Assistant version:
ha core update --version 2025.11.0
Restart Home Assistant safely:
ha core restart
Back up a file manually:
cp configuration.yaml configuration.yaml.bak
Watch your log file live:
tail -f home-assistant.log

Copy & Paste in the Web Terminal

In the browser terminal, Ctrl+C does not copy - it cancels a running command. Use these instead:

Copy: Hold Shift while dragging to highlight text, then right-click → Copy.
Paste: Press Shift + Ctrl + V (Windows/Linux).

If you copy and paste often, consider using a dedicated SSH app like PuTTY or Termius, which might make it easier.

Security Best Practices

Use SSH keys instead of passwords when possible.
Keep SSH access restricted to your local network or VPN.
Never open port 22 to the internet directly.
Back up configurations before editing.
Keep the add-on updated to receive the latest security patches.

Troubleshooting

"Command not found" for journalctl or docker? That's expected - they aren't available in the add-on shell.
"Connection refused" via SSH? Ensure the add-on is running and port 22 is open on your LAN.
Username is always root for this add-on.

Terminal vs. File Editor - When to Use Each

File Editor: Best for editing YAML files visually.
Terminal & SSH: Ideal for ha commands, creating backups, checking logs, and managing files when the UI isn't available.

Summary

The Terminal & SSH add-on gives you a reliable, powerful way to manage Home Assistant from the command line. Whether you're creating backups, checking logs, or restarting the system, it provides a fast, scriptable alternative to the web interface - perfect for both everyday users and troubleshooting emergencies.