Read File functions allow AI assistants to read file contents from the filesystem with built-in security controls that restrict access to designated directories.
Configuration function : type : read_file path : "{{ filename }}"
Path to the file to read. Can be absolute or relative to the working directory (config/extended_openai_conversation/).
Optional list of additional allowed directories (as templates). By default, only the working directory is allowed.
Working Directory The default working directory is config/extended_openai_conversation/.
Relative Path
Subdirectory
Absolute Path
# Reads from /config/extended_openai_conversation/notes.txt function : type : read_file path : "notes.txt"
# Reads from /config/extended_openai_conversation/data/config.json function : type : read_file path : "data/{{ filename }}"
# Reads from /config/automations.yaml (must be in allowed directories) function : type : read_file path : "/config/automations.yaml"
Examples Read File - spec : name : read_file description : Read a file from workspace. parameters : type : object properties : filename : type : string description : Name of the file to read required : - filename function : type : read_file path : "{{ filename }}"
Custom Allowed Directories Extend allowed directories beyond the default workspace. The allow_dir parameter adds additional directories where files can be read.
- spec : name : read_file_with_allow_dir description : Read a file with custom allowed directories. parameters : type : object properties : filename : type : string description : Name of the file to read required : - filename function : type : read_file path : "{{ filename }}" allow_dir : - "/backup" - "/media"
allow_dir accepts templates, so you can use variables like {{ config_dir }}:allow_dir : - "{{ config_dir }}/custom_components" - "{{ config_dir }}/www"
Return Value On success:
{ "content" : "file contents here..." , "size" : 1234 }
On error:
{ "error" : "File not found: filename.txt" }
Error Types
File not found : The specified file doesn’t existNot a file : The path points to a directoryFile too large : File exceeds 1 MB size limitAccess denied : File is outside allowed directoriesPermission error : Insufficient permissions to read file
File Size Limit Files larger than 1 MB (1,048,576 bytes) are blocked to prevent memory issues:
{ "error" : "File too large: 2097152 bytes (limit: 1048576)" }
For large files, consider using bash functions with head, tail, or grep to read specific parts: type : bash command : "head -n 100 {{ large_file }}"
Security
Files must be within allowed directories. By default:
/config/extended_openai_conversation/ (working directory) Additional directories can be added via allow_dir.
Path Traversal Protection
Paths are resolved to absolute paths and validated against allowed directories. Attempts to use ../ to escape allowed directories will be blocked: # BLOCKED - tries to escape allowed directory path : "../../../etc/passwd"
Files over 1 MB are automatically rejected to prevent memory exhaustion.
Files are read with UTF-8 encoding. Binary files may not be read correctly.
Use Cases
Configuration Review Read and analyze Home Assistant configuration files
Log Analysis Read log files to diagnose issues
Data Files Access JSON, YAML, CSV, or text data files
Script Review Read automation scripts and templates
Common Patterns Read YAML Configuration - spec : name : read_automation_config description : Read automation configuration parameters : type : object properties : {} function : type : composite sequence : - type : read_file path : "/config/automations.yaml" response_variable : file_content - type : template value_template : | {% set data = file_content.content | from_yaml %} Found {{ data | length }} automations: {% for auto in data %} - {{ auto.alias }} {% endfor %}
Read and Parse JSON - spec : name : read_json_data description : Read and parse JSON file parameters : type : object properties : filename : type : string function : type : composite sequence : - type : read_file path : "{{ filename }}" response_variable : file - type : template value_template : | {% if 'error' in file %} {{ file.error }} {% else %} {% set data = file.content | from_json %} {{ data }} {% endif %}
Search File Content - spec : name : search_in_file description : Search for text in a file parameters : type : object properties : filename : type : string search_term : type : string function : type : composite sequence : - type : read_file path : "{{ filename }}" response_variable : file - type : template value_template : | {% if 'error' in file %} Error: {{ file.error }} {% elif search_term in file.content %} Found "{{ search_term }}" in {{ filename }} {% else %} "{{ search_term }}" not found in {{ filename }} {% endif %}
Examples Read Multiple Files - spec : name : read_config_files description : Read multiple configuration files parameters : type : object properties : files : type : array items : type : string description : List of filenames to read function : type : template value_template : | {% for filename in files %} === {{ filename }} === {% set file = namespace(content='') %} {# In real implementation, use composite function to read each file #} {% endfor %}
To read multiple files, use a composite function that loops through each file, or create separate function calls for each file.
Read with Error Handling - spec : name : safe_read_file description : Safely read a file with error handling parameters : type : object properties : filename : type : string function : type : composite sequence : - type : read_file path : "{{ filename }}" response_variable : result - type : template value_template : | {% if 'error' in result %} Unable to read file: {{ result.error }} {% elif 'content' in result %} File: {{ filename }} Size: {{ result.size }} bytes Content: {{ result.content }} {% endif %}
Best Practices
Validate file paths
Always validate that requested files are appropriate to read: value_template : | {% if filename.endswith('.yaml') or filename.endswith('.json') %} {# Read file #} {% else %} Error: Only YAML and JSON files allowed {% endif %}
Handle errors gracefully
Check for errors in the response and provide helpful feedback: value_template : | {% if 'error' in file_result %} Could not read file: {{ file_result.error }} {% else %} {{ file_result.content }} {% endif %}
Be mindful of file size
Large files (>1MB) are blocked. For large files, use bash functions to read portions: type : bash command : "tail -n 50 {{ large_log_file }}"
Use appropriate allowed directories
Only add directories to allow_dir that the AI should legitimately access: # Good - specific purpose allow_dir : - "/config/www" - "/config/custom_components" # Bad - too broad allow_dir : - "/"
Troubleshooting
Access denied: path not in allowed directories
The file is outside allowed directories. Either:
Move the file to the workspace (/config/extended_openai_conversation/)
Add the file’s directory to allow_dir
Use an absolute path to /config/ if appropriate
The file exceeds 1 MB. Options:
Use bash functions to read portions (head, tail, grep)
Split the file into smaller chunks
Process the file externally and save results to a smaller file
Check:
File path is correct (relative to working directory)
File exists at the specified location
Path separators are correct (use / on all platforms)
Files must be UTF-8 encoded. For binary files or other encodings, consider using bash functions: type : bash command : "file {{ filename }} && xxd -l 100 {{ filename }}"
FAQ
No. Read File functions use UTF-8 text encoding. For binary files, use bash functions: type : bash command : "xxd {{ binary_file }} | head -n 20"
What's the maximum file size?
1 MB (1,048,576 bytes). This limit prevents memory issues when processing large files.
Can I read files outside /config?
Yes, by adding directories to allow_dir. However, the default workspace and /config are always available.
Are symbolic links followed?
Yes. Paths are resolved to their real locations, then validated against allowed directories.
Next Steps 
