hass-n8n Home Assistant Add-on

Nabu Casa

If using Nabu Casa, you must manually set the EXTERNAL_URL environment variable to your Nabu Casa remote URL. This is necessary for OAuth2 credentials to function correctly (setting the proper redirect URLs).

Manual External URL

If using a manual external URL, Ingress traffic is not safely relayed. You must expose port 5678 of the container to a port on Home Assistant (e.g., 5678) under the Network section of the add-on's configuration tab.

Because the add-on uses Home Assistant Ingress for the UI, webhooks, triggers, and the n8n API cannot be accessed through the standard Ingress (as they require unauthenticated public access).

To enable these features:

1. Expose port 8081 to the internet using a tunnel (e.g., the Cloudflared add-on).
2. Set the WEBHOOK_URL environment variable in env_vars_list to the URL of your tunnel.

This ensures that webhook traffic and API calls reach n8n without being blocked by Home Assistant authentication.

To install the n8n add-on in Home Assistant, you must first add the repository https://github.com/Rbillon59/hass-n8n to your Home Assistant add-on library.

Once the repository is added:

1. Navigate to Supervisor -> Add-on Store in your Home Assistant frontend.
2. Search for and select the hass-n8n add-on.
3. Click INSTALL.

The env_vars_list option is a required configuration field used to pass environment variables to n8n. You can add multiple variables via the UI using the format KEY: value.

Each entry must match the regular expression ^[A-Z_0-9]+: .*$.

Commonly used variables include:

• WEBHOOK_URL: The public URL for webhooks.
• EXTERNAL_URL: The public URL for n8n (required for OAuth2 redirect URLs).
• NODE_FUNCTION_ALLOW_EXTERNAL: A comma-separated list of npm packages allowed in the Code node.

env_vars_list:
  - "WEBHOOK_URL: <value here>"
  - "EXTERNAL_URL: <value here>"
  - "NODE_FUNCTION_ALLOW_EXTERNAL: lodash,moment"

By default, n8n 1.x blocks file writes outside its internal paths. To allow n8n workflows to write files to the Home Assistant mapped directories /share and /media, set the unrestrict_file_writes option to true in the add-on configuration.

Warning: This removes a file-access safety guard. Only enable this if you trust the workflows running in your instance.

If you lose access to your admin account, you can reset n8n's user management using the CLI. Note: This removes all existing user accounts and restores user management to its pre-setup state.

1. In the Configuration tab, set cmd_line_args to user-management:reset.
2. Save and Restart the add-on.
3. Monitor the Log tab until you see: Successfully reset the database to default user state.
4. Go back to Configuration, clear the cmd_line_args field, and Save.
5. Restart the add-on again. You will be prompted to create a new admin user.

cmd_line_args: "user-management:reset"

If you encounter a 401: Unauthorized error in a popup window while setting up OAuth-based credentials, it is likely a browser-specific issue.

Workaround: Copy the URL from the popup window and paste it directly into a new tab in your main browser window to complete the authorization.

To use external npm modules within n8n (e.g., in a Code node), you must set the NODE_FUNCTION_ALLOW_EXTERNAL environment variable in the env_vars_list configuration. Provide a comma-separated list of the package names.

Example to allow lodash and moment:

NODE_FUNCTION_ALLOW_EXTERNAL: lodash,moment