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. Each check/start command has a Copy button. Copy and run the check first, then the start command in the same Terminal window.

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.

macOS cannot verify the connector

The current native ZIP is not Apple Developer ID signed and notarized. macOS may block its first launch with a message that it cannot verify agentdata-connector is free of malware.

After confirming you downloaded the expected package from AgentData, follow Apple's app-opening instructions: try the check command, then open System Settings → Privacy & Security → Open Anyway for agentdata-connector and confirm Open. Rerun the check and start commands. This approves the individual application; keep system security protections enabled. If macOS reports detected malware or a damaged package, stop and contact support.

If the bundled Python is also blocked

The ZIP includes its own Python runtime under _internal; no separate Python installation is needed. macOS may block it separately after you approve agentdata-connector. Repeat System Settings → Privacy & Security → Open Anyway for Python, then rerun the check command.

For a package you have verified and explicitly trust, you can instead remove the download quarantine attribute from only this connector executable and its bundled runtime. In Terminal, open the extracted agentdata-connector folder containing install-macos.sh, agentdata-connector and _internal, then run:

xattr -dr com.apple.quarantine ./agentdata-connector ./_internal
bash install-macos.sh --check
bash install-macos.sh

This is a local security override for these files, not Apple notarization or a malware check. Do not apply it to your Downloads folder or other software. Do not use it when macOS reports detected malware or a damaged package; contact support instead. A managed Mac may require IT approval. The permanent distribution fix is signing and notarizing the entire bundled runtime.

Native installers (1.7.0 and later)

Use the installer for your operating system and processor when offered by AgentData. Portable ZIP downloads remain available for manual installation.

• Mac: double-click the .pkg, follow Installer, then open Applications → AgentData Connector.command. The current package is unsigned and may need Privacy & Security → Open Anyway. Packaging is not Apple notarization.
• Windows: open the .msi, choose the destination and finish setup. Open AgentData Connector in the Start menu. Windows may request approval for an unsigned installer. The MSI supports upgrade, repair and removal.
• Linux: install the .deb on Debian/Ubuntu-compatible x86_64 systems with glibc 2.35 or later. Open AgentData Connector in your applications menu or run agentdata-connector --menu. Other distributions can use the compatible portable ZIP.

In the connector menu, choose Import configuration and test and select the .env downloaded from AgentData Setup. Then choose Start, or optionally Enable automatic startup after the test passes. Startup runs as your normal user at login, using launchd on Mac, a user scheduled task on Windows or a user systemd service on Linux. Installation alone does not start polling or expose local data.

Configuration is stored separately from the program: ~/Library/Application Support/AgentData/connector/.env on Mac, %LOCALAPPDATA%/AgentData/connector/.env on Windows, or ~/.config/agentdata/connector/.env on Linux. Upgrades preserve these settings. Stop the connector before upgrading, install the new package, then test and restart. Removal leaves your private settings intact; disable automatic startup first. Keep the downloaded .env private and merge existing database/folder settings before importing a replacement.

Desktop app (1.8.0 preview)

Desktop packages version 1.8.0 and later include a small graphical app. The stable download remains 1.7.0 until the desktop release is available for your platform; the 1.7.0 Mac package uses the Terminal launcher described above.

• Mac: open Applications → AgentData Connector.app. A coloured dot in the menu bar shows its status.
• Windows: open AgentData Connector from the Start menu. Its status icon appears in the system tray.
• Linux desktop: open AgentData Connector from your applications menu. Tray support depends on the desktop environment. Servers can continue running the connector through Terminal without opening the desktop app.

If an existing connector ID appears, your settings have been preserved: click Test, then Start. Otherwise:

1. In the AgentData website, open Connectors → Local connector installations and choose the installation for this computer (for example, your named Mac connector).
2. Open Setup / Agent token and copy your connector’s Agent token. Generate a replacement only if you lost it; replacing it invalidates the old token.
3. In the desktop app, click Connect to AgentData, paste the token and click Verify and connect. The app identifies your connector and saves its settings automatically. No .env download or connector ID entry is needed. Use the connector Agent token, not a personal app/API key.
4. Choose Folder / database settings to select the local folder or configure the database, then click Start. Connected means the worker successfully contacted AgentData. A passed local Test checks configuration and prerequisites; it does not contact AgentData or the database.

The AgentData server address is prefilled. For a self-hosted or different server, enable Use a different AgentData server before verification. The app verifies the token over HTTPS; HTTP is allowed only for localhost.

Reconnecting the same installation and AgentData address retains existing folder/database settings. A different installation or address uses its own configuration. Import configuration (advanced) remains available for downloaded .env files and custom settings; hidden .env files are visible in its file picker. Settings are saved privately on this computer; the user does not need to edit the file manually.

Use Folder / database settings while stopped. The Folder tab provides Browse, Check folder access and Open folder. Its access check reports whether your user can read or write the selected folder without changing files. Save this access root, then connect its folder/subfolder in AgentData and configure a document scan schedule for new and changed files.

The Database tab supports PostgreSQL, SQL Server and MySQL host/port/database/username/password forms. Choose Source for reading data or Staging for a write destination; each role keeps its own connection settings. Use Connection URL (advanced) for other database types or custom driver options. SQL Server requires acceptance of the included Microsoft driver licence. Passwords and advanced connection URLs are masked.

Save and test database saves the selected settings and opens that database connection to run SELECT 1. It does not change data or start AgentData polling. The result appears in the activity log; the desktop app bounds the test so a slow connection does not block the interface. This is distinct from the main Test button, which checks local configuration and prerequisites.

The Service status card shows running/connected/offline state and the last successful AgentData contact. The coloured menu-bar/tray icon lets you reopen the app, start/stop/restart the worker or quit. Enable startup at login to run the app automatically after signing in.

The activity log is held in memory and is not automatically saved to disk. Save logs exports the current redacted view to a local file you choose; Clear log view clears the display. File listing, document inventory, reads, writes and deletes appear as connector jobs with descriptive labels. These are operation logs, not a complete document-processing audit. Folder change detection and processing history are managed by AgentData’s configured scans and schedules; view document inventory and processing status there. Logs shown in the desktop window come from workers it starts; a Terminal-started worker keeps its output in Terminal.

Stop waits for the current request/job to finish. Restart waits for the old worker to stop before starting another; opening the app does not create a second worker if Terminal or login startup already started one. Logs shown in the app come from workers it starts; Terminal-started workers retain their Terminal logs.

After testing, Enable startup at login enables the desktop app for future logins. This uses launchd on Mac, a current-user scheduled task on Windows, and desktop autostart on Linux. Use Start to connect immediately. Disable startup removes automatic startup. Closing the window keeps the app in the menu bar/tray; Quit app and stop connector exits it. On desktops without a tray, closing the window stops the connector and exits.

The Terminal interface remains available: agentdata-connector --menu, agentdata-connector --status, and agentdata-connector --stop on Mac/Linux. Windows users can run agentdata-connector.exe --status or --stop from the installed directory, or use Manage Connector.ps1. The desktop and Terminal interfaces share the same private configuration and worker lock. Signing/notarization is still pending; installing a desktop app does not remove OS security approval requirements.

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.

Installations, updates and removal

Local connector installations lists every registered installation, including those already attached to folders, source databases or staging databases. Attached connections are listed under their installation; an unused installation shows Installations without connections. Offline means the connector is not currently reporting; it does not mean the registration was deleted. A new installation appears offline until it starts successfully.

Expand Download and install — shared instructions above the connector lists, or the same collapsed section inside Setup / AGENT_TOKEN, to get the runtime matching its operating system and processor. Extract it into a separate directory, copy your existing .env into that directory, stop the old process, run the preflight check, and start the new runtime. Preserve the same installation ID and token so existing connections continue to use it. A download does not update a remote machine by itself.

Use Remove installation to forget an unused registration and revoke its token. Confirm removal in the dialog. Stop the connector on the machine first. This does not uninstall local software or delete documents. AgentData rejects removal while folder, source database or staging database connections still depend on that installation; remove those connections first.

Files and relational setup profiles

The download/setup section offers Files and Relational profiles. Both use the same connector runtime, so one installation can serve a folder and SQL database on the same machine. AgentData keeps them as separate connections with their own folder or database settings.

For quick setup, add the connection first, register or choose the installation, and download the generated .env together with the runtime ZIP. For files, enter the absolute local folder path; no database settings are required. For SQL, use the source/staging setup flow and keep database credentials on the connector machine. Do not replace an existing shared .env with a folder-only file without retaining any database settings you still use.

For a complete source checkout with a prepared Python environment, run from public/connectors/relational:

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

Set CONNECTOR_PYTHON to your prepared Python executable when using a different virtual environment. This source workflow is separate from the self-contained offline ZIP; it does not download dependencies for you.

Collapsible connector and storage sections

The connector screen groups connections, all local installations, storage status, and download/setup instructions into collapsible sections. Open Storage overview or choose Refresh storage status to inspect the configured file stores. Its header retains the observed file count, size and latest file modification time while collapsed. Unreachable stores are flagged and do not contribute successful counts.

Storage overview is a best-effort inspection of file stores, not a document change history or proof that extraction ran. Large inventories can be bounded by the storage inspection limits. Use Documents Automation for document inventories, scan times, scheduled change detection and processing results. Recurring scans detect new or updated documents using the selected template; connecting a folder alone does not turn monitoring on.

Rename an installation and choose it for SQL

Click the installation name (with its pencil icon), edit it inline and choose Save beside the name. Tenant administrators can rename their own installations; super administrators can also rename installations in other tenants. The name is a display label. The installation ID is the persistent key used by connections, and the token authenticates the runtime. A rename preserves both, so you do not need to edit .env or reconnect folders and databases. Changing a database or folder connection name is a separate operation.

To add a database using a specific installation, choose Connect a database on that installation's row. The form retains that installation and asks for a separate Database connection name. Use Choose a different installation only when needed.

The database picker lists registrations in the active tenant and shows their online/offline state, reported SQL readiness and hostname or installation ID. A never-started registration shows Capabilities not reported; it is not a default template. File-only registrations are hidden by default. Select Include installations that require SQL setup to use one for a database as well. Set SOURCE_DATABASE_URL in its existing local .env, preserve FILES_DIR and any staging settings, restart and refresh. Staging connections require STAGING_DATABASE_URL instead.

Register another installation is for another machine or a separate runtime. Give it an installation name independently of the database connection name. Reuse an existing registration when adding another connection to the same runtime; this prevents duplicate installations.

Configure local data once

An installation registration identifies a connector on your machine. AgentData connections are the automatically mapped data that installation provides. An offline registration cannot access your machine until its worker starts.

1. Open Setup / AGENT_TOKEN in AgentData. Generate a token if this is a new installation, then copy it.
2. Install and open the desktop connector. Paste the token into Connect to AgentData and verify it. Reuse your existing working token when available.
3. In the desktop connector, configure the Folder and/or Database tabs. Test database access locally. Save the settings, then start the worker (restart after later configuration changes).
4. AgentData automatically creates or updates the matching folder and database connections. Refresh the Connectors page if needed. Open the folder connection to browse its files. No additional folder path or database credentials need to be entered in AgentData.

One installation can provide both a folder and a database; these appear as separate data connections linked to the same installation. The folder mapping follows its local root. Database passwords remain on the machine. Existing mapped connection IDs are reused so flows retain their references. Setup / AGENT_TOKEN still provides token replacement, installation instructions, reported configuration and connectivity checks. Legacy .env setup remains available under advanced options.

The explorer is limited to FILES_DIR and accessible subfolders. It rejects parent/absolute paths and links outside the root. To expose a different root, change FILES_DIR on the machine and restart; the browser does not grant filesystem permissions. Setup browsing/testing requires an administrator in the installation's active tenant. Super administrators viewing multiple tenants must select the owning tenant before testing local access.

Machine details

The mapped folder path appears in bold below the connection name. Last seen appears beside the Online/Offline badge. Expand Machine details (closed initially) to see hostname, reported IP addresses, operating system and version, and the installed package path. These values come from the local connector; IPs are machine-reported addresses, not necessarily a public internet IP. Older connectors may show not reported for missing details. Update the local runtime to 1.6.1 or later for OS version and machine-only setup. A never-started installation shows Never connected. Previously reported machine information remains visible when the connector goes offline.

The installation name is editable, AGENT_ID is the stable mapping key, and AGENT_TOKEN authenticates the runtime. One installation can serve separate folder and database connections. Reusing a running installation with a working token does not require token replacement.

Replacing a connector token and checking online status

When you regenerate a token in Setup / Agent token, AgentData shows the new token once with Copy token. Copy it before closing the form, then in the desktop app stop the worker, open Connect to AgentData, paste the new token and verify it, then click Start. The replaced token stops working immediately. Existing tokens cannot be recovered from AgentData; generate another only if you lost the replacement.

Test machine connection / Refresh reports whether the selected installation is sending a recent heartbeat, or shows an error if the inventory could not be refreshed. Match the installation name and ID in the desktop app with the installation selected in AgentData. A running app window alone does not mean its worker is connected. File-connection Test results also appear beside the tested row.

Connector settings and AgentData mappings

The desktop connector owns the accessible folder root and database credentials. AgentData shows the reported root and safe database metadata (engine, database name, host and port). Passwords and full database connection URLs stay on the connector computer. After changing local settings, restart the worker so it reports the changes. Database metadata requires an updated desktop connector.

Configure the folder or database in the desktop connector, then start the worker. AgentData automatically creates or updates its matching connection. There is no second folder/database setup in AgentData. Folder connections follow the locally configured root, including later changes; existing connections keep their IDs so flows retain their references. One installation serving both folders and a database appears as two connections. The old .env generation controls are under Advanced .env configuration, for legacy/manual installations.

The file browser has Refresh files and optional Auto-refresh this file list while open. This refreshes listings; it does not enable background document processing or upload file contents automatically. To discover and process new/changed documents when the browser is closed, attach the folder in Documents and configure its scan/processing schedule. Running the connector only provides access; an obsolete folder mapping or absent schedule will not monitor new files.

Browse folders and save aliases

Click Open folder on a folder connection to browse its root and accessible subfolders through AgentData. This opens the folder browser; it does not launch Finder on the connector computer. Files remain on that computer.

To save a shortcut, open a subfolder, enter an Alias name, and click Save alias. Saved aliases appear below the connection and open their corresponding subfolders. Saving an existing alias name updates its shortcut. Remove alias removes only the shortcut, leaving files and existing Document Automation folder bindings intact. Aliases stay within the locally configured access root and survive connector reports and renames.

Start a Document Automation test

1. Open Document Automation → Documents → Connect folder.
2. Choose an existing folder connection, such as test_files_tal. The name follows the installation name; there is no separate sample connector to configure.
3. Use its root, select a saved subfolder alias, or browse and click Choose this folder. Enter a name for this document folder, then click Connect folder.
4. Click Scan folder to discover documents for testing. Processing and background schedules remain separately configured.

Create new connection opens the same connection gallery used in Connectors. For another local installation, register it, configure its folder in the desktop connector, and start it. Return to the folder picker and refresh; its automatically mapped connection becomes selectable. Cloud folder connections can also be created from the gallery.

Changing the installation name updates its mapped connections, the Document Automation connection picker, and Storage overview. Folder aliases and names you chose for document folder bindings retain their own labels.

Where document results are saved

Extracted values and review revisions are saved in the AgentData database, for local folders, S3 and managed uploads alike. Source folders hold the original documents. You do not need connector write permission to store extraction results.

When your tenant administrator configures Git synchronization under Settings → Git, new result revisions are committed under documents/projects/<project-id>/<document-id>/runs/<run-id>/revisions/<revision>/result.json, inside the configured repository directory. Each snapshot includes the populated result, its template and review metadata. Stable IDs keep history together when display names change.

Results show database persistence and the revision's Git status. A Git failure preserves the database result; an administrator can inspect and retry synchronization under Settings → Git. Initial repository setup includes retained earlier results that the configuring administrator can access. Revisions created before this feature in an already configured repository can show no Git snapshot.

Use Results to review, accept and download JSON/CSV. Publication to a separately selected database remains an explicit optional action. Git copies contain extracted customer values, so the selected repository must be private. Git history has independent retention: expiring a database result does not erase prior commits. Original PDF/image bytes and connector credentials are not copied to Git.