Files on disk

The team has a folder — on a server, on the department’s shared drive, on a NAS — holding what is in neither the task nor the code: policies in Word, budgets and registers in Excel, plans in PowerPoint, contracts in PDF, notes in text files. The integration lets the model read this folder the way a person does: a document — as text with headings and tables, a spreadsheet — by sheet, a presentation — by slide, a PDF — by page. Read-only; nothing is indexed or copied: a file is read at the moment of the question, and the answer shows which files were read.

Tools

The three tools are the same ones AI agents use to work with code files — in name, parameters and answer format: a model that knows them learns nothing new. The difference is in what is behind them: an Office file or a PDF is searched and read as text, a path can lead to a network folder, and everything stays within the connection’s scope.

The line number from grep is the same as read shows: found a line — read around it. Nothing is limited or truncated: not the number of files found, not the number of lines, not the line length. A file is read in pages only when the model itself asked for offset and limit.

Formats

The format is recognised by content, not by extension: a document renamed to .zip is still a document. Everything else — images, archives, a scanned PDF without a text layer, a password-protected file — the integration names by kind and size rather than pretending to have read it. Old formats are read as text: charts, images and embedded objects in them are not converted.

Paths and scope

A path is absolute local (/srv/docs/2026/plan.docx) or network, in any of three spellings: \\server\share\section, //server/share/section, smb://server/share/section. In answers a network path is always shown one way — smb://server/share/section: it survives JSON and markdown without escaping.

The connection lists roots — folders and, if you like, individual files; the bot works in them and in everything nested. The second field is exclusions: name and path patterns the bot does not see — *.bak, ~$* (Office temporary files), .git, archive/2019. A pattern is matched against a file or folder name at any depth and against the path from the root.

A path outside the roots is not read, even if the model names it exactly; a path through a symbolic link is checked by where it leads. An excluded file is found neither by search nor in a folder listing.

Local disk and permissions

The integration runs as a separate OS user — this is how the connector isolates each connection (see Isolation). This means local files must be readable by that user: a read permission “for everyone” (chmod -R a+rX) or a group that the connection’s user also belongs to. A file that cannot be read is visible in the list, and when read it is named together with the reason.

A connector in a container sees only what is mounted into the container: the folder has to be passed through — -v /srv/docs:/srv/docs:ro — and the path inside the container named as a root. A network drive mounted by the operating system (SMB via cifs, NFS) is a local folder too: pass it through the same way, and the connection then needs no password.

SMB network folder

The second way to a network drive is without mounting: the integration itself talks SMB to the server from the root. For this the connection needs an account and a password — create a separate one, read-only and only for the folder you need. The domain goes into the name: CORP\svc-buff or svc-buff@corp.local.

The integration speaks SMB 2.0.2 and 2.1 from the very first packet — without the SMB1 greeting, which is disabled on modern servers and NAS devices — signs in with NTLMv2 and signs the session if the server requires it. A server that needs only SMB3 with encryption cannot be connected this way: mount it with the OS’s means and connect it as a local folder.

The connections the integration opens itself are declared in its manifest — protocol, port and the field the addresses come from — and shown on the connection page next to the HTTP addresses: smb://nas.corp:445.

Setup

The connectivity check says how many of the listed roots are available, names the unavailable ones with the reason, and the account network folders are read under.

From the command line: connector install files, then connector instance set --plugin files --version 1.0.0 --set roots=/srv/docs,\\nas\docs --set excludes=*.bak and connector instance secret <connection> --secret share --account 'CORP\svc-buff' (the password comes from standard input).

What the integration does not do

• It does not write to disk — neither files nor comments; it has no writing tools at all.
• It does not index or copy content: files are read at the moment of the question. On a large folder a content grep means reading and parsing every file on every request; narrow the scope with roots and exclusions, and point the model to a folder or an include.
• It does not recognise scans and does not read images.
• It does not speak NFS, WebDAV or FTP — the OS mounts such a drive, and from then on it is local.
• It does not take requests in files — a folder has no comment feed; questions are asked in Buff (“Ask”, deep research) or by addressing the bot in a tracker or on a knowledge source’s page, and the files are context for the answer. Development tasks do not read the folder.