config.json, Timbal can explore it and copy its files into a knowledge base. The connector reads the files itself, in read-only mode, and only the share’s name and paths relative to it cross the connection.
Every request needs the connector online and the fs:browse capability (copying needs fs:copy), both reported by connector 0.1.27 or newer and only when at least one share is configured. Otherwise browse requests answer browse_unsupported (or fs_unsupported) and copy answers fs_unsupported.
Searching needs more than membership because reading file contents is data leaving your network.
Explore
1
List the shares
2
Summarize before you look inside
A cheap overview of a folder: counts, total size, the largest files and a breakdown by extension. Do this before listing or copying a big folder.
3
List one level
filesystem_ref, path (relative to the share), all, sort (name, size or mtime), glob, depth (default 0, so one level), limit, timeout_ms.4
Search file contents (optional)
filesystem_ref, path, pattern (a regular expression, matched per line), glob, max_matches, timeout_ms.Limits and partial answers
- Each request has a time budget on the server: 20 seconds by default.
timeout_mschanges it, up to 30 seconds. On a big or slow mount, pass a short one (5000) so you fail fast. - An answer can be partial. When
truncatedistruethe walk stopped at a limit. That is a normal result, not an error.summaryalso returns atruncated_reason. depthis capped at 8. List one level at a time instead of walking a deep tree.- A browse request can’t be cancelled once sent, and a single stuck network read can hold it until the operating system gives up. Copy jobs can be stopped; browse requests can’t.
connector_offline, browse_timeout, browse_unsupported (the connector lacks fs:browse), and fs_unsupported (no shares configured, or a connector older than 0.1.27). Copy answers 404 for an unknown connector or knowledge base.
Copy files to a knowledge base
Copying streams files from a share into a knowledge base’s document store. It is a job: you can list it with the other jobs and stop it. It needs the ConnectorsManage and K2Manage roles.- 100 MB per file. Larger files, empty files and symbolic links are skipped with a note. One failed file doesn’t fail the job.
- The job’s
rows_emittedcounts files that landed. - Run
summaryon the folder first to see whether it fits the limits.
Next steps
Connect your IDE
Explore a share from Cursor with
fs_du, fs_ls and fs_search.Configure connections
How to list a folder in
config.json.