open-webui-smb-tool/README.md

Open WebUI SMB File Operations Tool

An Open WebUI Workspace Tool for controlled SMB2/SMB3 file access.

The tool allows an Open WebUI model to browse, read, create, update, copy, move, and delete files on an SMB share while keeping SMB connection details and permissions in per-user UserValves.

Administrator Valves provide global policy controls such as server/share allow-lists, maximum file sizes, and whether write, delete, directory, and recursive operations are permitted.

The implementation uses the Python smbprotocol package through its high-level smbclient API.

Features

• SMB2/SMB3 access
• Per-user SMB server, share, username, password, and domain
• Optional SMB encryption
• Optional logical root directory inside a share
• Server and share allow-lists
• Path traversal protection
• Separate permissions for:
  • creating files
  • modifying existing files
  • deleting files/directories
  • directory operations
  • move/copy operations
• Administrator-controlled read/write/search limits
• Text and Base64 file reads/writes
• Chunked file reads using byte offsets
• Exact text replacement for safer file updates
• Recursive wildcard file search
• Open WebUI status reporting through EventEmitter
• SMB session/cache isolation between Open WebUI users

Requirements

The tool declares:

smbprotocol>=1.17.0

The Open WebUI runtime hosting the tool must be able to reach the SMB server, normally on TCP port 445.

The SMB account must also have the filesystem/share permissions required for the operations you enable.

Installation

Download or copy:

open_webui_smb_file_operations.py

into Open WebUI as a Workspace Tool.

A typical workflow is:

1. Open Workspace in Open WebUI.
2. Open Tools.
3. Create a new Tool.
4. Paste the contents of open_webui_smb_file_operations.py.
5. Save the Tool.
6. Configure the administrator Valves.
7. Give the intended users access to the Tool.
8. Each user configures their own UserValves.
9. Use test_connection before enabling write operations.

The tool metadata specifies:

required_open_webui_version: 0.6.3
requirements: smbprotocol>=1.17.0

Ensure the Open WebUI Python environment is able to install/use the declared dependency.

---

Configuration

Administrator Valves

Valves define the global policy for every user of the Tool.

enabled

Default:

true

Global on/off switch.

Setting this to false prevents SMB operations for all users.

allowed_server_patterns

Default:

*

Comma-separated fnmatch patterns controlling which SMB servers users may configure.

Examples:

nas01

nas01,fileserver01

*.internal.example

nas*,10.20.*

For a production installation it is recommended to replace * with the specific SMB servers Open WebUI is supposed to access.

Example:

nas01.internal.example,nas02.internal.example

allowed_share_patterns

Default:

*

Comma-separated patterns controlling which SMB shares may be used.

Example:

Documents,Engineering,Projects-*

A production configuration should normally restrict this rather than leaving it as *.

allow_create_files

Default:

true

Allows users to opt in to creating new files.

A user must additionally enable:

allow_write_new_files

in their own UserValves.

allow_modify_files

Default:

true

Allows users to opt in to changing existing files.

This affects operations such as:

• overwriting files
• appending data
• text replacement
• replacing an existing copy/move destination

The user must additionally enable:

allow_modify_existing_files

allow_delete_paths

Default:

false

Global delete permission.

Deletion is intentionally disabled by default.

To allow deletion, both of these must be enabled:

Administrator:

allow_delete_paths = true

User:

allow_delete_existing_paths = true

allow_directory_operations

Default:

true

Controls creation/manipulation of directories.

Users must additionally enable:

allow_directory_operations

allow_move_copy

Default:

true

Allows users to opt in to copy and move operations.

Users must additionally enable:

allow_move_copy_operations

allow_recursive_delete

Default:

false

Controls recursive directory deletion.

This is a separate administrator protection in addition to normal delete permissions.

Keeping this disabled is recommended unless recursive deletion is specifically required.

allow_alternate_data_streams

Default:

false

Controls whether : is permitted in relative SMB paths.

On Windows-compatible filesystems a colon can address an Alternate Data Stream.

Normally leave this disabled.

max_read_bytes

Default:

2097152

2 MiB.

Maximum amount returned by one read_file call.

Large files can be read in chunks using offset.

max_write_bytes

Default:

4194304

4 MiB.

Maximum payload accepted by a single write, append, or update operation.

max_list_entries

Default:

500

Maximum number of entries returned from a single directory listing.

max_search_results

Default:

200

Maximum results returned by search_files.

max_search_depth

Default:

8

Maximum recursive depth permitted for search_files.

---

UserValves

Each user has their own SMB connection and permissions.

server

SMB hostname or IP address.

Example:

nas01.internal.example

Do not enter:

smb://nas01/Documents

or:

\\nas01\Documents

Only the server name/IP belongs here.

port

Default:

445

Normally this should remain 445.

share

SMB share name.

Example:

Documents

For:

\\nas01\Documents

configure:

server = nas01
share  = Documents

username

SMB username.

Example:

openwebui

password

Password for the SMB account.

The field is presented as a password input in Open WebUI.

domain

Optional Windows/Active Directory domain.

Example:

CORP

With:

domain   = CORP
username = jdoe

authentication is performed as:

CORP\jdoe

If the username already contains \ or @, the tool leaves it unchanged.

Examples:

CORP\jdoe

or:

jdoe@example.com

root_path

Optional directory inside the SMB share that becomes the logical filesystem root for this Tool.

Example:

OpenWebUI

With:

server    = nas01
share     = Documents
root_path = OpenWebUI

the actual SMB base becomes:

\\nas01\Documents\OpenWebUI

The model only supplies paths relative to this location.

For example:

projects/report.md

maps to:

\\nas01\Documents\OpenWebUI\projects\report.md

Using root_path is strongly recommended because it limits the portion of the share exposed to the Tool.

encrypt

Default:

false

When enabled, the SMB connection requests SMB encryption.

The SMB server must support the required SMB3 encryption features.

Consider enabling this when SMB traffic crosses networks where confidentiality cannot otherwise be guaranteed.

connection_timeout

Default:

30

SMB connection timeout in seconds.

---

User Write Permissions

All mutation permissions default to disabled for users.

This means the initial configuration is effectively read-only.

allow_write_new_files

Allows creation of new files.

Requires administrator:

allow_create_files = true

allow_modify_existing_files

Allows changes to existing files.

This includes:

• overwrite
• append
• update_file
• replacing existing copy/move destinations

Requires administrator:

allow_modify_files = true

allow_delete_existing_paths

Allows deletion.

Requires administrator:

allow_delete_paths = true

allow_directory_operations

Allows directory creation and directory-related move/delete operations.

Requires administrator:

allow_directory_operations = true

allow_move_copy_operations

Allows copy and move operations.

Requires administrator:

allow_move_copy = true

---

Recommended Initial Configuration

For initial testing, keep the Tool read-only.

Administrator:

enabled = true

allowed_server_patterns = nas01.internal.example
allowed_share_patterns = OpenWebUI

allow_create_files = true
allow_modify_files = true
allow_delete_paths = false
allow_directory_operations = true
allow_move_copy = true
allow_recursive_delete = false
allow_alternate_data_streams = false

max_read_bytes = 2097152
max_write_bytes = 4194304
max_list_entries = 500
max_search_results = 200
max_search_depth = 8

User:

server = nas01.internal.example
port = 445
share = OpenWebUI
username = openwebui
password = <password>
domain =
root_path =
encrypt = true
connection_timeout = 30

allow_write_new_files = false
allow_modify_existing_files = false
allow_delete_existing_paths = false
allow_directory_operations = false
allow_move_copy_operations = false

Run:

test_connection

before enabling any write permissions.

---

Available Tool Functions

test_connection

Tests:

• SMB connectivity
• authentication
• share access
• logical root_path

No credentials are returned in the result.

Example request:

Test the SMB connection.

---

list_directory

Lists files and directories.

Parameters include:

path
pattern
include_hidden

Example:

List the root directory.

Example:

List all PDF files in Reports.

Equivalent tool arguments could be:

path = Reports
pattern = *.pdf

The result includes:

• name
• relative path
• file/directory type
• size
• created time
• modified time
• accessed time

---

stat_path

Returns metadata for a file or directory.

Example:

Show information about Projects/report.md.

---

read_file

Reads file data.

Supports:

• text
• configurable encoding
• Base64
• byte offset
• maximum byte count

Example:

Read Notes/todo.txt.

For a binary file:

Read image.png as Base64.

Large files can be processed incrementally:

offset = 0
max_bytes = 1048576

followed by another call with:

offset = 1048576

The administrator max_read_bytes always takes precedence.

---

search_files

Recursively searches for filenames using wildcard patterns.

Examples:

*.pdf

report*

*.csv

Parameters include:

pattern
start_path
max_depth
include_directories

Example:

Find all CSV files below Data.

---

write_file

Creates a new file.

It can also overwrite an existing file when:

overwrite = true

Creating a file requires:

Valves.allow_create_files = true
UserValves.allow_write_new_files = true

Overwriting requires:

Valves.allow_modify_files = true
UserValves.allow_modify_existing_files = true

Example:

Create Notes/example.txt containing "Hello world".

By default:

overwrite = false

which prevents accidental replacement of an existing file.

The operation also supports Base64 content for binary data.

---

append_file

Appends text or binary data to a file.

Requires modification permission when the file exists.

Example:

Append a line to Logs/manual.log.

A missing file can optionally be created using:

create_if_missing = true

Creating the missing file additionally requires create permission.

---

update_file

Performs exact text replacement in a text file.

This is useful when the model should make a small controlled change instead of rewriting the entire file.

Example:

Existing:

server=old-server
port=445

Request:

Replace "server=old-server" with "server=new-server".

The operation supports:

replace_all
expected_replacements

expected_replacements can be used as an additional safety check.

For example:

expected_replacements = 1

causes the operation to fail rather than modify the file if the requested replacement would affect a different number of occurrences.

For sensitive configuration files this is recommended.

---

make_directory

Creates a directory.

Supports:

parents
exist_ok

Example:

Create Projects/2026/Reports and create missing parent folders.

This requires directory-operation permission.

---

copy_file

Copies a file within the configured SMB share/root.

Example:

Copy Templates/report.md to Projects/report.md.

If the destination already exists, replacement requires:

overwrite = true

and modification permission.

---

move_path

Moves or renames files and directories within the configured SMB share/root.

Example:

Rename Drafts/report.md to Drafts/report-old.md.

or:

Move Drafts/report.md to Published/report.md.

Directory moves require directory-operation permission.

---

delete_path

Deletes a file or directory.

Deletion is disabled by default at both policy and user levels.

A normal file delete requires:

Valves.allow_delete_paths = true
UserValves.allow_delete_existing_paths = true

Deleting an empty directory additionally requires directory operations.

Recursive directory deletion additionally requires:

Valves.allow_recursive_delete = true

Example:

Delete Temp/file.txt.

Recursive delete should only be enabled when there is a clear operational requirement.

---

Path Security

All model-supplied paths are relative paths.

The Tool rejects:

• UNC paths
• absolute paths
• drive-letter paths
• .. traversal
• Alternate Data Stream syntax unless explicitly enabled

For example, this is valid:

Projects/Report.txt

These are rejected:

..\..\secret.txt

\\another-server\share\file.txt

C:\Windows\file.txt

The configured SMB server/share cannot therefore be replaced through a normal file-operation argument.

The root_path setting provides an additional confinement boundary within the configured share.

---

SMB Session Isolation

The Python smbclient implementation maintains a process-wide connection/session cache.

This matters in a multi-user Open WebUI instance because different users may configure different SMB credentials.

The Tool therefore:

1. serializes SMB access with a process-wide lock,
2. clears the smbclient connection cache before an operation,
3. registers only the current user's SMB session,
4. executes the operation,
5. clears the connection cache again afterward.

This prioritizes credential/session isolation over parallel SMB operation throughput.

If very high SMB concurrency is required, this design should be reviewed before changing the locking/session model.

---

EventEmitter Status Reporting

All public operations use the included EventEmitter.

The Tool reports:

in_progress

while an SMB operation is executing.

On completion it reports either:

success

or:

error

with:

done = true

This provides visible operation status in Open WebUI while the model is working with the SMB share.

---

Security Recommendations

Use a dedicated SMB account

Do not use a personal administrator account.

Create an SMB/service account specifically for Open WebUI.

Give that account only the filesystem permissions required for the intended use.

For a read-only Tool, the SMB account itself should preferably also have read-only permissions.

Application-level permission controls should not be the only protection.

Use a dedicated share or directory

Prefer:

\\nas01\OpenWebUI

or configure:

root_path = OpenWebUI

instead of exposing a broad company/user share.

Restrict servers and shares

Avoid production settings such as:

allowed_server_patterns = *
allowed_share_patterns = *

Prefer explicit values:

allowed_server_patterns = nas01.internal.example
allowed_share_patterns = AI-Documents

Keep delete disabled unless required

Recommended default:

allow_delete_paths = false
allow_recursive_delete = false

Keep Alternate Data Streams disabled

Recommended:

allow_alternate_data_streams = false

Use SMB encryption where appropriate

When supported by the server:

encrypt = true

SMB encryption protects SMB payloads in transit.

Protect stored credentials

UserValves.password contains an SMB credential.

Configure Open WebUI so sensitive Valve values are protected appropriately, and protect the Open WebUI database, backups, configuration, and secret keys.

Do not give Tool-administration access to users who should not be able to change its security policy.

Use least privilege at both layers

There are two distinct permission layers:

1. SMB filesystem/share permissions
2. Tool Valves / UserValves

Configure both.

For example, if an account only needs read access, make it read-only on the SMB server even if the Tool's write switches are accidentally changed later.

---

Suggested Permission Profiles

Read-only

Administrator:

allow_create_files = false
allow_modify_files = false
allow_delete_paths = false
allow_directory_operations = false
allow_move_copy = false
allow_recursive_delete = false

User mutation switches:

false

Use for knowledge/document retrieval.

Read + create

Administrator:

allow_create_files = true
allow_modify_files = false
allow_delete_paths = false

User:

allow_write_new_files = true
allow_modify_existing_files = false
allow_delete_existing_paths = false

Useful when the model may generate new reports but must never alter existing documents.

Read + create + update

Administrator:

allow_create_files = true
allow_modify_files = true
allow_delete_paths = false

User:

allow_write_new_files = true
allow_modify_existing_files = true
allow_delete_existing_paths = false

This is a reasonable general-purpose document-management profile.

Full file management

Administrator:

allow_create_files = true
allow_modify_files = true
allow_delete_paths = true
allow_directory_operations = true
allow_move_copy = true

User:

allow_write_new_files = true
allow_modify_existing_files = true
allow_delete_existing_paths = true
allow_directory_operations = true
allow_move_copy_operations = true

Consider leaving:

allow_recursive_delete = false

unless recursive removal is truly needed.

---

Example Open WebUI Prompts

Once the Tool is enabled for a model, typical prompts include:

List the files in the Reports directory.

Find all PDF files under Projects.

Read Projects/README.md and summarize it.

Create Notes/meeting.txt with the following notes...

Change "server01" to "server02" in Config/application.conf.
Only make the change if there is exactly one occurrence.

Copy Templates/monthly-report.md to Reports/2026-08.md.

Move Drafts/report.md to Approved/report.md.

The language model decides which Tool function to call based on the function descriptions and parameters.

---

Troubleshooting

Connection refused or timeout

Verify:

• SMB server hostname/IP
• TCP port 445
• routing between Open WebUI and the SMB server
• host firewall
• container/network firewall
• SMB service availability

If Open WebUI runs in Docker, test connectivity from the Open WebUI container/network rather than only from the Docker host.

Authentication failure

Check:

• username
• password
• domain
• SMB account status
• server authentication policy

For Active Directory, try either:

domain = CORP
username = jdoe

or configure the username directly as:

CORP\jdoe

or, where supported:

jdoe@example.com

Access denied

Successful authentication does not imply filesystem access.

Check both:

• SMB share permissions
• underlying filesystem/NTFS permissions

Also verify that the corresponding Tool/UserValve mutation permission is enabled.

Server not allowed

If the Tool reports that the server is not allowed, check:

allowed_server_patterns

Example:

nas01.internal.example

must match the user's:

server

Share not allowed

Check:

allowed_share_patterns

against the configured:

share

Cannot create or modify files

Check both administrator and user controls.

Creating:

Valves.allow_create_files
UserValves.allow_write_new_files

Modifying:

Valves.allow_modify_files
UserValves.allow_modify_existing_files

The SMB account itself must also have write permission.

Cannot delete files

Deletion requires:

Valves.allow_delete_paths = true
UserValves.allow_delete_existing_paths = true

Recursive directory deletion additionally requires:

Valves.allow_recursive_delete = true

File is too large

Read and write operations are constrained by:

max_read_bytes
max_write_bytes

Use chunked reads for large files.

For very large file transfer workloads, this Tool is intentionally not optimized as a bulk SMB transfer utility.

Binary file cannot be decoded

Use:

as_base64 = true

with read_file.

For binary writes, provide Base64 and use:

content_is_base64 = true

Update text was not found

update_file performs exact text replacement.

Whitespace, line endings, capitalization, and encoding therefore matter.

Read the relevant part of the file first and use the exact existing text.

---

Limitations

• Operations are confined to one configured SMB server/share/root per user.
• Copy/move functions operate inside that configured logical SMB root.
• SMB operations are serialized to protect per-user session isolation.
• The Tool is intended for controlled model-driven file operations, not high-throughput file transfer.
• update_file performs exact text replacement rather than semantic document editing.
• Large files are constrained by administrator-configured limits.
• SMB permissions remain ultimately controlled by the SMB server and filesystem ACLs.
• The Tool cannot grant permissions that the configured SMB account does not possess.

---

File Layout

A simple deployment/repository layout could be:

open-webui-smb-tool/
├── open_webui_smb_file_operations.py
└── README.md

---

Version

Tool version:

0.1.0

Minimum declared Open WebUI version:

0.6.3

Python dependency:

smbprotocol>=1.17.0

---

License

MIT