# Files on disk
> Server folders and SMB network folders as context: Word, Excel, PowerPoint (2007+ and 97–2003), PDF and text — the glob, grep and read tools; read-only.
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.
_Illustration: A question whose answer is written down only in a document in a network folder: the model found the file with the grep tool, read it and answered from it — with the file path._
## 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.
| Tool | What it does |
|---|---|
| `glob` | searches files **by name** — a pattern such as `*.docx`, `**/contract*`, case-insensitive; across the whole scope or in a folder; newest first |
| `grep` | searches **by content** — a regular expression over the text of files, including the text of documents, spreadsheets, presentations and PDFs; answers with the file, the line number and the line |
| `read` | reads a file **in full** as numbered lines — or a folder as a list; `offset` and `limit` — if the model needs a part |
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
| What | How it is read |
|---|---|
| Word `.docx`, `.docm` | markdown: headings, paragraphs, lists, tables, links, text boxes |
| Excel `.xlsx`, `.xlsm` | each sheet as a table with the header from the first row; dates as dates, not as a number of days |
| PowerPoint `.pptx`, `.pptm` | slide by slide: title, text, tables, speaker notes |
| Word 97–2003 `.doc` | the document text: paragraphs, lists, table cells |
| Excel 97–2003 `.xls` | sheets as tables, numbers and dates — as in the new format |
| PowerPoint 97–2003 `.ppt` | slide text and notes |
| PDF | page by page, the text layer |
| Text files | as is: `.txt`, `.md`, `.csv`, `.json`, `.xml`, `.yaml`, `.html`, code — UTF-8 or Windows-1251 |
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.
A scan is a picture. For a PDF without a text layer the integration honestly says “no text
layer, pages: N”; text recognition (OCR) is not part of it.
## 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.
**An empty list of roots means “the whole disk of the connector’s machine”** — everything readable
by the user the integration runs as. Network folders are not affected: they are accessed with
a password, and the model must not name the server that password goes to by itself — a network folder
is available only through a 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](/en/docs/connector/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`.
This is the only kind of credentials the connector **passes to the integration**: SMB is not
HTTP, and the connector cannot insert the password on the plugin’s behalf. The catalogue shows this before installation
(“passed to the integration itself”), and the request log shows every hand-over. All other integrations
do not see their secrets.
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`.
_Illustration: The setup form: roots — local and network — exclusions, the network folder’s account and password._
## Setup
| Field | Value |
|---|---|
| Folders | comma-separated roots: `/srv/docs`, `\\nas\docs\specs`, `smb://nas/docs/regulations.docx`; empty — the whole disk of the connector’s machine |
| Exclusions | comma-separated patterns: `*.bak`, `~$*`, `.git` |
| Account for `share` | `CORP\svc-buff` — needed only for network roots |
| Password for `share` | that account’s password; passed to the integration |
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 --secret share --account 'CORP\svc-buff'` (the password comes
from standard input).
_Illustration: Connectivity check: how many roots are available and which account network folders are read under._
## 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.