> ## 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.

# Integrations

> Connect instruments and workstations with managed integrations

Integrations automatically detect and upload data from your local tools and workstations to Atomscale. Each integration is a small connector program that the Atomscale desktop app downloads, runs, and supervises for you. From the **Integrations** page you can install integrations, configure them, and monitor their status.

<Note>
  Integrations are managed from the [Atomscale desktop app](/platform/reference/desktop-app). The
  **Integrations** page is not available when using the platform in a browser.
</Note>

## How Integrations Work

An integration collects data from a local source, such as a watched folder or an instrument, and hands it to the desktop app. The app buffers the data on disk, then uploads it to Atomscale over HTTPS using your signed-in session.

```text theme={null}
 Local source              Atomscale desktop app                Cloud
┌─────────────┐    ┌───────────────────────────────────┐    ┌───────────┐
│ Instrument, │ →  │ Integration → buffer → upload     │ →  │ Atomscale │
│ folder, ... │    │               (disk)    queue     │    │ platform  │
└─────────────┘    └───────────────────────────────────┘    └───────────┘
```

A few properties of this design are worth knowing:

* **No machine credentials**: Integrations never hold API keys and never connect to the network themselves. All uploads go through the desktop app, authenticated as the signed-in user.
* **Durable buffering**: Data is stored on disk until it is uploaded, so network outages and app restarts do not lose data.
* **Sign-out safe**: If you sign out, integrations keep collecting data locally and uploads pause. Uploading resumes automatically when you sign back in.

Each installed integration is independent, with its own configuration, status, and activity log. You can install multiple copies of the same integration, for example to watch two different folders, and rename each copy to tell them apart.

## Adding an Integration

<Steps>
  <Step title="Open the Integrations page">
    Select **Integrations** in the desktop app sidebar.
  </Step>

  <Step title="Open the catalog">
    Click <Badge stroke color="blue">Add Integration</Badge>. A dialog lists the integrations
    available to your workspace.
  </Step>

  <Step title="Add an integration">
    Click <Badge stroke color="blue">Add</Badge> on the integration you want. The app downloads
    the connector and verifies its checksum before installing it.
  </Step>

  <Step title="Configure it">
    When installation completes, you are taken to the integration's configuration page.
  </Step>
</Steps>

<Note>
  Adding an integration only downloads it. It does not upload anything until you configure and
  start it.
</Note>

Some catalog entries may be temporarily unavailable, for example when an integration is not built for your operating system or requires a newer version of the desktop app. Hover over a disabled entry to see the reason.

## Configuring an Integration

Open an integration from the Integrations table, then click <Badge stroke color="blue">Configure</Badge>. A running integration must be stopped before its configuration can be changed.

The configuration form has two tabs:

* **Standard**: The settings most installations need, such as paths, device identifiers, and grouping options. The available fields depend on the integration.
* **Advanced**: Optional tuning settings. Every integration includes an **Upload Backlog Size Limit**, which caps how much unsent data is buffered on disk (blank means automatic, based on free disk space), and **Free Disk Space To Keep**, which sets the amount of disk space the buffer will never consume.

Fill in the form and click <Badge stroke color="blue">Apply Configuration</Badge>. Invalid values are highlighted inline; the integration itself also validates the configuration and can reject specific fields, in which case the affected inputs are highlighted with the reason.

<Note>
  Applying a configuration saves it but does not start the integration. Start it explicitly when
  you are ready to collect data.
</Note>

## Starting and Stopping

Use the <Badge stroke color="blue">Start Integration</Badge> and <Badge stroke color="blue">Stop Integration</Badge> buttons on the integration's detail page. The desktop app remembers this choice: integrations you started are launched automatically the next time the app opens, and integrations you stopped stay stopped.

If an integration crashes, the app restarts it automatically with an increasing delay. An integration that crashes repeatedly in a short window is **quarantined**, meaning the app stops restarting it. After fixing the underlying problem, press <Badge stroke color="blue">Resume Integration</Badge> to clear the quarantine. Restarting the desktop app also clears it.

## Monitoring

The Integrations table shows each installed integration with its name, type, version, and current status. You can search by name and filter by type. Click a row to open the detail page, which includes:

* **Details**: The connector, its description, type, and installed version.
* **Health**: Current status, last successful upload, and running time.
* **Upload Queue**: The state of pending data uploads for this integration.
* **Activity Logs**: A searchable history of events, filterable by severity, with an option to open the log files on disk.

An **Advanced** tab on the detail page exposes process, delivery, and disk diagnostics for troubleshooting and support.

### Status Reference

| Status               | Meaning                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------- |
| **Starting**         | The integration is launching.                                                               |
| **Running**          | The integration is collecting and uploading data.                                           |
| **Stopped**          | The integration is not running.                                                             |
| **Uploads paused**   | The integration is collecting data, but uploads are paused (for example, while signed out). |
| **Error**            | The integration reported a problem. Check the activity logs for details.                    |
| **Quarantined**      | The integration crashed repeatedly and the app stopped restarting it.                       |
| **Update available** | A newer version can be installed.                                                           |
| **Revoked**          | The installed version was withdrawn and will not run. Update or uninstall it.               |

## Updating an Integration

The desktop app checks for new integration versions at launch and every few minutes afterward. You can also check on demand with the refresh control next to the search box. Updates are never installed automatically.

When an update is available, the integration shows an **Update available** badge and its detail page shows an **Update Available** card with the new version. Click <Badge stroke color="blue">Update Integration</Badge> to install it.

* If the integration is running, the update briefly suspends uploading while the new version is installed, then the integration restarts automatically. Buffered data is preserved.
* Releases marked as a **Breaking change** may migrate your saved configuration to a new format. The migration happens automatically during the update.
* If an update fails, the previous version is restored automatically and a notice explains what went wrong.

## Uninstalling an Integration

Open the integration's configuration page, switch to the **Advanced** tab, and use <Badge stroke color="blue">Uninstall integration</Badge> under **Danger zone**. Uninstalling stops the integration and removes its local program and configuration. You can reinstall it again at any time.

## Upload Settings

Upload bandwidth and the number of simultaneous file uploads are controlled per computer, not per integration, under **Data Ingestion** in your account settings. Changes apply immediately to all active integrations. Timeseries data is prioritized over file uploads so that live monitoring stays responsive.

## Technical Details

This section summarizes networking and security behavior for IT teams evaluating integrations for deployment.

* **Outbound HTTPS only**: All communication with Atomscale uses TLS on port 443. Integrations do not open listening ports or accept inbound traffic.
* **Downloads are verified**: Integration programs are downloaded from Atomscale over HTTPS and verified against a SHA-256 checksum before installation.
* **Process isolation**: Each integration runs as a separate local process with no network access of its own. It can only hand data to the desktop app.
* **Authentication**: Uploads are authenticated with short-lived tokens tied to the signed-in user. No long-lived credentials are stored on the machine.
* **Local storage**: Configuration, logs, and buffered data live under the desktop app's application data directory. Buffered data is kept until it uploads successfully, up to a 30-day limit.
* **Local logs**: Integration activity logs are written as daily files under the desktop app's application data directory, at `%APPDATA%\Atomscale\gateway\logs\`. You can also open this folder directly from an integration's **Activity Logs** section.