Skip to main content
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

1

Download the installer

Open the Add Data dialog in the sidebar, then select the File Watcher tab. Click Download File Watcher to get the installer.
2

Install the application

Run the downloaded installer and follow the on-screen prompts.
3

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.

​
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.
Optical image file names should be sequentially numbered (for example, img_001.jpg, img_002.jpg) so they are ordered correctly after upload.

​
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.
DestinationPurpose
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.