Connect a folder on your computer

A folder connector lets AgentData access an approved folder on your computer. On macOS and Linux, it supports document discovery and original-file reads. Keep the connector running while using that folder. Preview and extraction can transfer document contents to AgentData for processing; select a folder approved for that use.

Connect an existing folder

1. Sign in and select your tenant and project.
2. Open Documents Automation → Documents → Connect folder.
3. Choose an existing folder connection. The list contains the folder connections available to your project; unsupported document connections are marked and cannot be selected.
4. Enter a recognizable folder name and continue to Review.
5. Leave Relative folder empty to use the connection's root, or enter a child folder such as invoices. Do not enter an absolute path here.
6. Choose Connect folder, then Scan to discover documents.

Connect a new folder on your Mac

An administrator can create a new connection directly from Connect folder → New local folder connection. The same setup is also available in Connectors → Add source → File & Storage → On-Prem Connector.

The wizard keeps the same window throughout setup. Use Back and Next without losing your entries. Close and the close button stay available; long instructions scroll inside the window.

1. Name: enter a folder name and choose Connector (local folder). This means a folder on the computer running the connector. Local means a folder on the AgentData server.
2. Connect: choose an available connector, or register a new one. A connector already assigned to another source requires a separate registration.
3. Install: for a new connector, follow the installation steps below. To reuse an installed connector, keep its current configuration and leave Install or reconnect this connector unchecked.
4. Review: check the connection and optional relative subfolder, then save. A saved connection may be offline until its connector starts.

Install from scratch

The installation screen shows the latest connector version at the top.

1. Select macOS and Apple Silicon or Intel to match your Mac. Download and extract the entire verified connector ZIP. Do not run an installer from inside the ZIP.

2. Enter the absolute path of an existing folder on your Mac, for example /Users/your-name/Documents/invoices. The downloaded .env sets this as FILES_DIR. Put .env beside the connector executable in the extracted directory.

3. Open Terminal in that directory and run:

   bash install-macos.sh --check
   bash install-macos.sh

   The first command checks the configuration without connecting to a database or the network. The second starts the connector. No database configuration is needed for a folder-only connection.

4. Keep the connector running. Return to AgentData and check that it shows Online, finish setup, then scan the connected folder.

On Linux, use the Linux download and bash install-linux.sh --check, followed by bash install-linux.sh. Safe document-folder access on Windows remains unsupported.

Existing folder and connection token

An installed connector's folder is configured locally in its .env. Reusing that connector does not ask you to re-enter the folder or replace its token. To change the root folder, update FILES_DIR locally and restart; then rescan the connection.

The connection token authenticates that connector to AgentData. A new registration includes its token in the .env download. Keep the file private on the connector computer. You do not need to generate another token for normal use.

Use Replace lost connection token only when the token was lost or you are moving the installation. Replacement immediately invalidates the previous token. Update the connector's .env and restart it before expecting it to reconnect. Do not run two installations with the same token.

Watch for new or changed documents

Connecting a folder does not automatically schedule extraction.

1. Scan the folder and create a saved extraction template.
2. Open Monitoring → Extraction results and select the template version and any required runtime inputs.
3. Select Scheduled folder, choose an interval in minutes, and choose Schedule folder.
4. Keep the connector running and inspect the schedule and processing results. Use Disable to stop the schedule.

This performs recurring scans, rather than an immediate operating-system file watcher. Files are processed against the selected template version. Human review and acceptance still apply.

Troubleshooting

What you see	What to do
Only server folders in Connect folder	Create a new local folder connection, or ask an administrator to assign your existing connector-backed folder to this project.
No available connector	Register a new connector; an existing one may be assigned elsewhere or unavailable to your tenant.
Folder field empty during a new installation	Enter the actual path on the connector computer before downloading its configuration. Existing local paths are not retrieved from that machine into the form.
Connector offline	Check that the installer is running, .env is beside the executable, the token is current and outbound HTTPS is available.
Native executable missing	Extract the complete downloaded native ZIP. A source-code directory is a different development workflow.
Scan returns no documents	Confirm the root/subfolder and permissions, then scan again.
Partial scan or changed original	Resolve the reported issue and rescan before treating the inventory as complete.

For document review, templates, accepted results and outputs, continue with Documents Automation.