> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atomscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File Watcher

> Automatically upload files from a local directory

The File Watcher is a desktop application that monitors a local directory and uploads new files to Atomscale automatically. It is useful when your instruments write data to a shared folder and you want that data to appear in the platform without manual intervention.

## Installation

<Steps>
  <Step title="Download the installer">
    Open the <Badge stroke color="blue">Add Data</Badge> dialog in the sidebar, then select the <Badge stroke color="blue">File Watcher</Badge> tab. Click <Badge stroke color="blue">Download File Watcher</Badge> to get the installer.
  </Step>

  <Step title="Install the application">
    Run the downloaded installer and follow the on-screen prompts.
  </Step>

  <Step title="Generate an API key">
    The File Watcher authenticates with your API key. If you don't already have one, generate a key from **Add Data > API Integration** or from **Profile > Account Management**. Copy and save the key; it is only displayed once.
  </Step>
</Steps>

## Configuration

Open the File Watcher and go to the **Settings** tab. The following settings control how files are detected and uploaded.

### Watch Path

The absolute path to the directory the File Watcher monitors (for example, `/Users/lab/atomcloud_sync`). Use the **Browse** button to select a directory.

### API Key

Paste the API key you generated in Atomscale. The File Watcher validates the key on entry, so you will see an error if it is invalid or expired.

### Traversal Depth

Controls how many directory levels below the watch path to scan. Set to **0** to watch only the top-level directory, or increase it to detect files in subdirectories. For example, a depth of **2** reaches files two folders deep.

### Group Uploaded Files

When enabled, files are organized into physical samples based on the name of their top-level folder within the watch path. For example, if the watch path contains folders `GBL_UNLIT/` and `DR1_CAST/`, each folder becomes a physical sample in Atomscale.

### File Coalescing

Glob patterns that consolidate multiple files into a single data item after upload. For example, adding `*.jpg` and `*.txt` as patterns means all JPEG files in a folder are grouped into one data item, and all text files into another. Patterns are matched against file names only, scoped to each top-level folder.

### Auto Upload

When enabled, newly detected files are uploaded automatically. This toggle resets when the watch path changes to prevent accidental uploads.

## Folder Structure

The File Watcher expects files to be organized by sample. Under the watch path, create a folder for each sample, then place the associated files inside it:

```
watch_path/
├── GBL_UNLIT/
│   ├── img_001.jpg
│   ├── img_002.jpg
│   ├── ...
│   └── metrology.txt
├── DR1_CAST/
│   ├── img_001.jpg
│   ├── img_002.jpg
│   ├── ...
│   └── metrology.txt
```

With **Group Uploaded Files** enabled and coalescing patterns set for `*.jpg` and `*.txt`, each top-level folder maps to a physical sample, optical images are consolidated into one data item, and metrology files into another.

<Tip>
  Optical image file names should be sequentially numbered (for example, `img_001.jpg`,
  `img_002.jpg`) so they are ordered correctly after upload.
</Tip>

## Uploading Files

Files can be uploaded three ways:

* **Per file**: click the upload icon on any row in the **Files** tab.
* **Bulk**: select multiple files and choose **Upload eligible files** from the actions menu.
* **Automatic**: enable **Auto Upload** in Settings to upload new files as they appear.

Upload progress and status are shown in the Files tab. Each file transitions through **Pending**, **Queued**, **Uploading**, and **Uploaded** (or **Error** if something went wrong). Files that errored can be retried.

## Advanced Settings

Under the collapsible **Advanced Settings** section you can:

* **Polling**: enable polling-based file detection, which is more reliable for network or cloud storage drives.
* **Await File Stability**: wait for a file's size to stabilize before processing, which prevents uploading files that are still being written.
* **Reset Settings**: clear all configuration and return to defaults.

## Technical Details

This section covers system requirements, networking, and security information for IT teams evaluating the File Watcher for deployment.

### Application Overview

The File Watcher is a lightweight desktop application built on Electron. It runs in user space and does not install system services, modify system-level settings, or require administrator privileges. It monitors a user-selected directory for new files and uploads them to Atomscale over HTTPS.

### System Requirements

* Windows 10 or later (macOS and Linux are also supported)
* Minimal resource footprint: under 200 MB of disk space and roughly 100 MB of RAM during normal operation
* Outbound internet access to the Atomscale API and AWS S3

### Installation and Updates

The Windows installer is a standard Squirrel-based `.exe` that installs to the current user's `AppData\Local` directory. No elevated permissions or administrator approval is needed.

The application checks for updates automatically (once per hour) and notifies the user when a new version is available. Updates are downloaded in the background and applied only when the user chooses to restart. All installers and updates are code-signed with SHA-256.

### Network Requirements

The File Watcher makes **outbound HTTPS connections only**. It does not open any listening ports or accept inbound traffic.

| Destination                           | Purpose                                                    |
| ------------------------------------- | ---------------------------------------------------------- |
| Atomscale API (`api.atomscale.com`)   | Authentication, upload coordination, and pipeline triggers |
| AWS S3 (`s3.us-east-1.amazonaws.com`) | File upload via time-limited presigned URLs                |

No VPN, firewall exceptions for inbound traffic, or special DNS configuration is required. If your network uses an allowlist for outbound traffic, permit HTTPS (port 443) to the destinations above.

### Authentication and Security

* **Authentication**: API key passed in a request header. No cookies, session tokens, or stored passwords.
* **Encryption in transit**: all communication uses TLS/HTTPS. There is no HTTP fallback.
* **Upload authorization**: files are uploaded to S3 using presigned URLs that expire after one hour.
* **Code integrity**: the application bundle is packaged as a signed, read-only archive (ASAR) with integrity validation enabled.
* **Process isolation**: the UI renderer has no direct access to Node.js or the file system. All operations go through a controlled bridge between the interface and the main process.

### Local Data Storage

The application stores its configuration (watch path, API key, upload history) in a small JSON file under the user's application data directory:

* **Windows**: `%APPDATA%\atomcloud-file-watcher\`
* **macOS**: `~/Library/Application Support/AtomCloud File Watcher/`

Log files are written alongside the configuration and automatically rotate at 1 MB. No uploaded file content is cached locally.