Watch Folders
A scanner drops pages into a shared folder; an hour later they should be searchable, redacted and archived. A watch folder does that: every file that lands in it starts a durable run of a workflow (or an agent) under an API key, and the file moves on when the run ends.
1Open the folder to the server#
A watched folder must sit inside a directory the server may read: the file ingest roots on
Admin > Connect > MCP. The same boundary governs file_ingest, so a watch can never read
anything an agent could not.
2Build the pipeline as a workflow#
A workflow receives the file as vars.file_path (where it is being processed) and vars.file_name
(the name it landed with). Its first step brings the file into the document store; the steps after
it work on what that step returns.
{
"schema_version": 1,
"name": "archive-scan",
"steps": [
{ "id": "ingest", "type": "tool", "tool": "file_ingest", "arguments": { "path": "{{vars.file_path}}" } },
{ "id": "archive", "type": "agent", "agent": "archivist",
"input": "Run OCR on the file registered here, redact personal data, convert it to PDF/A and file it: {{steps.ingest.output}}" },
{ "id": "check", "type": "approval", "message": "File {{vars.file_name}} in the archive?",
"document": "{{vars.file_path}}", "approve_when": "contains(steps.archive.output, 'no personal data found')" }
]
}
The last step is a review: a file the archivist found clean files itself, and the others wait in the Approvals inbox with the scan open beside the decision. Publish it from Admin > Build > Workflows (see Agent Workflows).
3Watch the folder#
Open Admin > Connect > Watch folders and choose New watch folder:
| Field | What it sets |
|---|---|
| Folder | The absolute path of the watched directory, inside an ingest root |
| Files | Patterns such as *.pdf;*.tif; empty counts every file. Only files directly in the folder count |
| At most at once | How many files may be in progress together (running or waiting for a person) |
| Starts | The workflow (or agent) each file starts |
| Input | The run's input: {{file.path}}, {{file.name}}, {{file.extension}}, {{file.size}} |
| Runs as | The API key whose grants, owner and quotas the runs use |
4What happens to a file#
| Stage | Where the file is |
|---|---|
| Landing | In the folder. It is left alone until it stops changing (the same size and write time on two passes) and nothing else holds it open, so a scan still being written is never taken |
| In progress | Moved to <folder>/.lmkit/processing before its run starts, so no pass takes it twice; it stays there while its run waits for an approval |
| Done | <folder>/.lmkit/done when the run completes (or hands the work to a person) |
| Quarantined | <folder>/.lmkit/quarantine when the run fails or a person denies it, with an alert on Admin > Operate > Alerts: nothing is lost silently |
Files on a watch's row lists every file it picked up, where it is now, why it was quarantined, and opens its run. Records are kept a month.
5Large drops#
A watch never has more than its at most at once number of files in progress; the others wait in the folder. Each file is admitted against the key's quota before it is picked up: past the quota, files wait for the next window instead of failing. A 10,000-file dump therefore drains at the pace the server and the key allow, and interactive traffic keeps its share.
One node of a farm scans the folders (the watch-folders job holds a lease, listed on
Admin > Operate > Jobs), every five seconds.