Home Assistant Guide

Using the File Editor Add-on in Home Assistant

The File Editor add-on (previously known as the Configurator) allows you to directly edit files on your Home Assistant system through a browser. It's especially useful for quickly changing your configuration.yaml file or editing scripts, automations, and other configuration files without needing SSH or Samba access.

Installing the File Editor Add-on

To install the File Editor:

• Go to Settings → Add-ons → Add-on Store.
• Search for File Editor and click on it.
• Click Install and wait for it to finish.
• Once installed, enable Start on boot and Show in sidebar (if you want quick access).
• Then click Start to launch it.

After starting the add-on, it will appear in your sidebar (or under Settings → Add-ons if you haven't pinned it).

Adding File Editor to the Sidebar

If it doesn't automatically appear in the sidebar, you can manually enable it:

• Go to Settings → Add-ons → File Editor.
• Under the add-on's options, turn on Add to sidebar.
• Now you'll see a link on the left-hand side that opens the editor directly.

Common Uses

The File Editor is a convenient way to edit YAML configuration files, such as:

• configuration.yaml - for your main Home Assistant setup.
• automations.yaml and scripts.yaml - for creating or editing automations and scripts manually.
• secrets.yaml - to safely reference sensitive information like API keys.

It's also handy for creating or modifying .txt, .json, or .yaml files used by integrations or blueprints.

Limitations and Known Issues

• No ownership or permissions control: You can't fix permission errors directly in File Editor if a file belongs to another user (like root).
• Lag with large files: Performance can drop when opening very large YAML or log files.
• No full YAML validation: It checks basic syntax, but not deeper logical errors or missing keys.
• No autocomplete or context help: Unlike VS Code or Studio Code Server, File Editor doesn't suggest entity IDs or actions.
• No autosave or version backup: Always manually save your work using the Save button.
• No search function: You can't search for text across files within the editor.

For larger edits or frequent configuration changes, many users prefer the VS Code add-on instead.

Accessing the Add-on Configuration

To configure the File Editor add-on, open it from:

• Settings → Add-ons → File Editor → Configuration tab

This configuration is separate from the in-editor settings and must be accessed through the add-on page itself. The main options include:

• Directories First: Lists folders before files in the sidebar tree.
• Enforce Basepath: Restricts access to the /config directory for safety.
• Git: Enables Git initialization in supported folders.
• Ignore Pattern: Lets you hide specific folders (e.g. __pycache__, .storage).
• SSH Keys: Allows private keys for Git repository access.

Best Practices

• Always back up your configuration before editing manually.
• Use Check Configuration under Settings → System → Repairs after editing YAML files.
• Keep changes small and test after each one to make troubleshooting easier.
• Consider using secrets.yaml for passwords and API keys rather than writing them directly.
• If you frequently edit YAML, the Studio Code Server add-on offers better syntax highlighting, search, and Git integration.

The File Editor is perfect for quick tweaks and lightweight edits - but for complex work, a more full-featured editor is worth installing.

VS Code Add-on: Power vs. Simplicity

While the File Editor is very straightforward - open a file, make changes, click save - the VS Code (Studio Code Server) add-on is a full development environment running inside Home Assistant. It's designed for users who are comfortable with:

• Multiple tabs and panels
• Keyboard shortcuts like Ctrl + F and Ctrl + Shift + F
• File navigation and Git integration
• YAML validation and autocomplete

Beginners might find it a little overwhelming at first, since it has more buttons, menus, and features than are needed for simple edits. However, once you get used to it, it becomes much safer and faster - especially since it helps catch YAML errors before restarting Home Assistant.

In short:
👉 File Editor = simple and beginner-friendly
👉 VS Code = powerful and advanced, great once you're confident with YAML

Troubleshooting

• "/config" and "/homeassistant" are the same: Don't worry if guides online refer to one and you see the other in your setup. Depending on how Home Assistant is installed (e.g. OS, Container, or Supervised), these paths point to the same directory where your configuration files live.
• Need to access files outside the config folder? Uncheck Enforce Basepath in the File Editor add-on's configuration. This allows browsing and editing outside /config - for example, if you want to access log files or backups - but use this carefully to avoid accidental changes to system files.
• Editor won't save changes: Check file permissions or ownership - sometimes files created by other add-ons (like Node-RED or Docker containers) may be owned by root and require different access.
• Changes not taking effect: Remember that most YAML-based changes only apply after you reload integrations or restart Home Assistant. Use Settings → System → Restart or Developer Tools → YAML → Reload options as needed.
• File Editor missing from sidebar: Revisit the add-on's settings and toggle Show in sidebar back on. If it still doesn't appear, restart the add-on.
• Accidentally broke configuration? Use your latest backup or restore a snapshot. You can also open home-assistant.log in File Editor to check for error messages that explain why Home Assistant failed to start.

These small issues are common, especially after editing YAML files for the first time - but they're easy to fix once you know where to look!