Files on disk
Company documents · publisher buff · version 1.0.3
Folders on the server and SMB network folders as context: Word, Excel, PowerPoint — new and old formats — PDF and text. Read only, no index.
An answer in Buff relies on a PDF from a network folder — with the file name and the folder. The setup form: folders — including network ones — and exclusions. The connection is live: three tools, all read only; next to it, the network folder it reaches over SMB. The connection check: how many of the selected folders are available and which account the network folder is read with. What the integration will get is visible in the catalogue before installation — including the fact that the password is handed to the integration itself.
Click a screenshot to open it in full. All screenshots are from a working installation.
Overview
The team has a folder — on a server, on the department’s shared drive, on a NAS — holding what is neither in the task nor in the code: procedures in Word, budgets and registers in Excel, plans in PowerPoint, contracts in PDF, notes in text files. The integration lets Buff read that folder the way a person does — with the same three tools the model uses for project files: find by name, find by content, read. A local folder or an SMB network folder, Office 2007+ and 97–2003 formats, PDF. Read only; nothing is indexed or copied — a file is read at the moment of the question.
Use cases
The situations it is installed for.
The contract is a PDF on the shared drive
An analyst is asked which deadlines and amounts are fixed in the contract with a contractor. The contract is a PDF in the “Legal/2026” folder on the network drive; it is not in the tracker and will never get into the code.
Result. The bot finds the file by the word “contract” in its content, reads the PDF page by page and answers from it — with the full path to the file, so the answer can be checked.
A procedure in Word 2003 that nobody converted
The instructions for restoring from the archive were written in 2019 as a .doc and have sat in the “old” folder ever since. There is nobody to ask: the author has left, and nobody can be bothered to open the old format.
Result. The old format is read the same way as the new one: the integration parses the binary Word 97–2003 document and returns the text — paragraphs, lists, table cells.
The limits are written in a spreadsheet
A developer is writing a Jira integration and wants to know the requests-per-minute limit agreed with security. The limits are kept in Excel — the “Limits” sheet, a row per system.
Result. The bot searches for “Jira” by content, finds the row on the “Limits” sheet and answers with the number from the spreadsheet. Dates in the spreadsheet arrive as dates, not as a number of days since 1900.
Examples
What to write and what comes back. How the bot is addressed is set in the connection settings — here it is “@buff”.
What is the number of the services contract with sole trader Kungur, and until when is it valid? Look in the files.
“Ask” in Buff
tool:
grep → readContract No. 77-AB/2026, valid until 31 December 2026. Source: smb://nas/docs/2026/contracts/contract.pdf, page 1.
Which roadmap presentations are there for 2026?
a comment in an issue
tool:
glob/srv/docs/2026 has two presentations: roadmap.pptx (updated 12 September) and roadmap-q3.pptx (July).
What does the “On call” section of the release procedure say?
research
tool:
readThe “On call” table: Friday — Kungur, Saturday — Vorontsov. Document: /srv/docs/regulations.docx, “On call” section.
What it does
Three tools, as for project files
`glob` finds files by name (`*.docx`, `**/contract*`), `grep` by content with a regular expression, `read` reads a whole file as numbered lines or a folder as a list. The names, parameters and response format are the same as for project files: the model needs no new habits. Nothing is capped: not the number of matches, not the number of lines, not their length; a file is read in pages only when the model asks.
Office and PDF — as text
A Word document arrives as markdown with headings, lists, tables and links; an Excel spreadsheet as a table per sheet, with dates as dates; a presentation slide by slide with speaker notes; a PDF page by page. The 97–2003 formats (`.doc`, `.xls`, `.ppt`) are read the same way — the integration parses them itself. The format is recognised by content, not by extension; what cannot be read is named by type and size.
A network folder without mounting
A root such as `\\nas\docs\specs` is read by the integration itself over SMB — from the very first packet over SMB2, without the SMB1 greeting that is disabled on modern servers and NAS devices; sign-in by NTLMv2, session signing if the server requires it. A read-only account is needed: the connector hands it to the integration, and it is the only kind of credential the integration sees — the catalogue says so before installation.
Scope: roots and exclusions
The bot works in the roots and in everything nested; a root can also be a single file. Exclusions — `*.bak`, `~$*`, `.git` — hide a file from both search and folder listings. A path outside the roots is not read, even if the model names it exactly. An empty list of roots means the whole disk of the connector’s machine; this does not apply to network folders: they are available only through a root, because they are reached with a password.
How to use it
Everything happens on the machine where the connector runs. At no step do you need to open access to your network from outside.
Step 1
Installation and permissions
Install the integration from the catalogue on the connector’s local page. It runs under a separate OS user, so local files must be readable by that user (`chmod -R a+rX` or a shared group); for a connector in a container, the folder must be mounted into it (`-v /srv/docs:/srv/docs:ro`).
Connector← scroll the frame →
The access limits are written on the catalogue card. Step 2
Setup: roots, exclusions, an account
Name the roots separated by commas — local paths and network folders in any notation (`\\server\folder`, `smb://server/folder`), and exclusions if you like. Network roots need an account (`CORP\svc-buff`) and a password; local ones need nothing more.
Connector← scroll the frame →
Each integration has its own form fields. Step 3
The same from the command line
Installing without a GUI is an equal option: `connector install files`, then `connector instance set --plugin files --version 1.0.0 --set roots=/srv/docs,\\nas\docs --set excludes=*.bak`, and the password with `connector instance secret … --secret share --account CORP\svc-buff` from standard input.
Access limits
The connector shows the same on your machine before installation. The list comes from the signed catalogue, not written here by hand.
Goes out to
nowhere over HTTP; it opens its own connections: smb to the addresses from the field roots, port 445
Credentials
share — share is handed to the integration itself: the connector cannot speak its protocol for it
Webhooks
does not accept
| Tool | What it does | Access |
|---|---|---|
| glob | Find files by name — a pattern such as *.docx or **/contract*, in all the listed folders or in one; newest first | read only |
| grep | Find by content — a regular expression over the text of documents, spreadsheets, presentations, PDF and text files; file, line number, line | read only |
| read | Read a file as text (a document as markdown, a spreadsheet by sheets, a presentation by slides, a PDF by pages) or a folder as a list; whole, or in pages by offset/limit | read only |
The integration runs as a separate process under its own operating system user: it does not see the connector’s key, does not read the files of other connections and cannot reach the network past the connector — except for the connections declared above. More in the security section.
Requirements
- A folder on the connector’s machine (or a network drive mounted by the OS) — readable by the connection’s user; in a container, mounted into it.
- For a network folder without mounting — an SMB 2.0.2 or 2.1 server (Windows Server 2008 R2 and later, Samba, NAS) and a read-only account; a server that requires SMB3 with encryption only is connected through an OS mount.
- Connector 0.11 or later: credentials handed to the integration and the declaration of its own connections were added in it; an older connector will refuse to install the integration and name both versions.
- A connector run with the right to create a separate OS user for the integration (root or CAP_SETUID).
Questions
- Will the bot be able to change or delete anything?
- No. The integration has three tools, and all of them only read; there are no writing tools at all. It is sensible to give the account read-only access to the network folder — then the server guarantees it too.
- Why is the network folder password handed to the integration when the others do not get theirs?
- SMB is not HTTP: the connector cannot insert the password into a request on the plugin’s behalf — the plugin speaks the protocol itself. So this kind of credential is declared separately in the manifest, the catalogue shows it before installation, and every handover is written to the log. No password is needed at all if the drive is mounted by the OS and connected as a local folder.
- Does a big folder mean it takes long?
- Search by content reads and parses files at the moment of the request — nothing is indexed, and that is a deliberate decision: the content is not copied to us. Narrow the scope with roots and exclusions; a model that knows the folder will name it or a name pattern, and the search will cover less.
- Are scans readable?
- No. A PDF is read by its text layer; a scan has none, and the integration says so — “no text layer, pages: N”. Text recognition is not part of it.
- Are old .doc, .xls and .ppt files readable, or only new ones?
- Both. The integration parses the 97–2003 formats itself: text, lists and table cells from Word, sheets with numbers and dates from Excel, slide text and notes from PowerPoint. Charts, pictures and embedded objects in them are not converted.
Next
Connect Files on disk
Install the connector in your network, open its local page and install the integration from the catalogue. Nothing needs to be rebuilt.
Companies and sole traders can pay by bank transfer and receive closing documents