Access and Maintenance

How to Set Up a Samba Share in Home Assistant

Install the Samba share app, set a login, and connect from Windows or macOS to edit Home Assistant files. Covers allowed hosts and shared folders.

On this page
  1. Quick answer
  2. Check that your install supports it
  3. Install and configure the app
  4. Start the app and check its log
  5. Connect from Windows
  6. Connect from macOS or Linux
  7. Which folders the app shares
  8. Limit who can connect
  9. Common problems
  10. Keep it secure
  11. Samba share, Samba Backup and network storage

Quick answer

Install the Samba share app, set a username and password on its Configuration tab, and start it. Then connect from Windows with \\homeassistant.local\config, or from macOS with smb://homeassistant.local. If the name does not resolve, use the device’s IP address instead.

Check that your install supports it

The Samba share app runs only on Home Assistant OS and Home Assistant Supervised installs. It is not available for Home Assistant Container or Core. On those, use the file sharing built into the computer that runs Home Assistant.

Install and configure the app

  1. Open Settings > Apps (called Add-ons in older releases) and open the app store.
  2. Find Samba share, select it, and choose Install.
  3. Open the Configuration tab and set a username and password. They do not have to match your Home Assistant login. The app will not start without them.
  4. Save the configuration. Leave the workgroup as WORKGROUP unless your network uses a different one.

Use a strong, unique password, because it is the main protection for your configuration files.

Start the app and check its log

Select Start, then turn on Start on boot so the share returns after a restart. You can also turn on Watchdog, which restarts the app if it stops. If the share does not appear, open the app’s log, which shows startup errors.

Connect from Windows

  1. Open File Explorer and select Map network drive.
  2. Enter \\homeassistant.local\config, or \\<IP-address>\config if the name does not resolve.
  3. Select Connect using different credentials, then enter the Samba username and password.

Windows can keep old credentials and cause login failures. If the connection keeps failing, remove the saved credentials for that address in Windows Credential Manager and try again.

Windows 10 and 11 block guest access to SMB shares by default, so you need the username and password.

Connect from macOS or Linux

  • macOS: In Finder, choose Go > Connect to Server, then enter smb://homeassistant.local or smb://<IP-address>. Pick the share you want from the list.
  • Linux: Use smbclient to browse the shares, or the cifs-utils package to mount one.

Use an SMB address like the ones above. A web address such as http:// will not open the share.

Which folders the app shares

The app shares a fixed set of standard Home Assistant folders, including config, ssl, share, backup, media and addons. The list can change between versions, so check the app’s documentation tab for the current set.

The config share contains configuration.yaml, secrets.yaml and the hidden .storage folder. Anyone with the Samba login can read and change those files.

Editing YAML over Samba does not apply your changes until you reload or restart. See how to update and reboot Home Assistant safely for the reload options.

Limit who can connect

  • Allowed hosts. The allow_hosts setting limits which IP ranges can connect. The default covers the private home ranges (10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16). If you can, narrow it to your own subnet.
  • Compatibility mode. compatibility_mode allows old SMB1 clients. It is off by default. Leave it off unless a device you need only supports the old protocol, because those protocols are insecure and slow.

Common problems

  • The login keeps failing. Check the username and password on the Configuration tab, restart the app after any change, and clear the saved Windows credentials as described above.
  • The name does not resolve. Use the IP address instead.
  • Ports are blocked. SMB uses TCP port 445, and NetBIOS can use port 139. A firewall or router on your network may block them.
  • Changes do not show up. Reload or restart Home Assistant after editing YAML.

Keep it secure

  • Keep the share on your home network. Never forward port 445 to the internet.
  • Use a strong password, because the config share exposes sensitive files.
  • Back up before you make bulk edits. See how to back up and restore Home Assistant.
  • If you do not need file access most of the time, stop the app when you are finished.

Samba share, Samba Backup and network storage

People often mix up three different things:

  • Samba share app (this guide) shares Home Assistant’s folders with your computer.
  • Samba Backup is a separate community app that copies backups to a NAS. It has its own settings.
  • Network storage (Settings > System > Storage) connects a NAS or network folder to Home Assistant, for example for media or backups.

For access to Home Assistant’s own sign-in and network settings, see how to access Home Assistant.

The complete guide to access and maintenance

How to Access Home Assistant: URLs, Default Login, Tokens and SSO
Read the guide

Keep exploring

Guides from other topics

All topics →