Skip to main content
After you list a folder in 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

Parameters: 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)

Parameters: 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_ms changes 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 truncated is true the walk stopped at a limit. That is a normal result, not an error. summary also returns a truncated_reason.
  • depth is 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.
Errors (HTTP 422): 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_emitted counts files that landed.
  • Run summary on the folder first to see whether it fits the limits.
See Copy files to a knowledge base.

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.