Benchling Connect setup guide: installing the Gateway, configuring Data Connectors, and automating Analysis

Benchling Connect is a flexible, open data platform that enables scientific R&D teams to seamlessly automate data capture, manage data, and perform analysis. This guide outlines key setup and operational details for installation, configuration, automation with Analysis, and guidance for common troubleshooting workflows, including: 

• How to install and configure Benchling Gateway to automate data sync via:
  • Local Windows
  • Direct AWS S3
• How to configure the data connector for data processing using:
  • Out-of-the-box Data Connector
  • Connector Build Tools
• How to automate analysis with Benchling Analysis

Get started with Benchling Connect

Prerequisites

• Connect is available to customers who have the Benchling Connect package enabled in their Benchling tenant. If you’re unsure whether your tenant is licensed, please contact your Customer Success representative or reach out to support@benchling.com
• Admin access to your Benchling tenant
• Necessary permissions for reading or writing data to your data source

Data source & connectivity overview

Benchling Connect supports ingesting your data from various sources, processing that data, and enriching it through metadata-aware workflows. Key components include:

• Benchling Gateway to sync data from various sources including:
  • Local Windows
  • Network Drive
  • Cloud - S3

• Data Connector (bi-directional API and file-based) to process data via:
  • Out-of-the-box connector supporting key instruments that are standardized using Allotrope Simple Model (ASM)
    • Learn more in our open-source repository here
  • Connector Builder path with a bi-directional file watcher capability

• Data processing capabilities in Connect Run
  • Out-of-the-box data transformation tools
  • Automation capabilities such as
    • Entity registration, Inventory transfer, Result capture
    • Automated Connect → Analysis workflow

For more information about how Connect is deployed within your environment and how data is securely transmitted into Benchling, see the linked whitepaper in Benchling's Trust Portal. To view the document, you may need to request access. 

Benchling Gateway Overview

The Benchling Gateway facilitates secure data transfer between your laboratory instruments and the Benchling platform. Installing the gateway enables you to automate data ingestion directly from instrument output folders into Benchling, eliminating the need for manual file handling. You can choose between two installation options based on your lab's infrastructure and data flow preferences:

• Standard Local Gateway Installation: Best suited for instruments running on a secure, local network. Installing the gateway directly on a nearby computer enables real-time access to instrument files and ensures compatibility with IT and access control policies
• Cloud Gateway (S3-Based): Ideal for organizations that use cloud-native file storage (e.g., AWS S3) or need to support multiple sites. This option allows Benchling to connect to a cloud bucket where instruments drop their files, facilitating remote and distributed access

Standard local Gateway installation 

Before installing the local Gateway, confirm that your system meets these additional minimum requirements and network configuration allows communication with required endpoints. 

Local environment server and network setting requirements

Before installing the Benchling Gateway, ensure your environment meets the following requirements. This ensures smooth installation and reliable file transfer between your systems and Benchling:

Architecture: x86_64 (also known as x64)

Supported Operating Systems:

• Windows 10 or later (64-bit)
• Windows 11
• Windows Server 2016 or later

Required Permissions:

• Local Administrator rights are required to install or upgrade the gateway
• The gateway runs under the benchgw_user system user, which must have read/write access to instrument folders

Firewall and Antivirus Considerations:

• Allowlist the gateway installer and service in any antivirus or endpoint protection tools.
• Open outbound HTTPS connections to Benchling domains (typically https://<your-tenant>.benchling.com)

Disk Space and Memory:

• Minimum 2 GB of available disk space
• Minimum 4 GB of memory recommended for environments processing large output files

Minimum hardware

• Minimum 256MB disk space for AWS IoT Greengrass Core software (excludes deployed components) 
• 160MB RAM for AWS IoT Greengrass Core software (excludes running components)

Port

If your network settings only allow traffic through particular ports, check if the traffic is being allowed through port 443. This can be verified by running the following command in PowerShell:

Test-NetConnection -Port 443 -ComputerName benchling.com -InformationLevel Detailed

Add required endpoints

If your network restricts traffic to specific endpoints, add these AWS endpoints to your allowlist:

• greengrass-ats.iot.region.amazonaws.com
• *.s3.amazonaws.com
• *.s3.region.amazonaws.com
• *-ats.iot.region.amazonaws.com
• *.credentials.iot.region.amazonaws.com

Note: Replace region with your tenant's AWS region (for example, us-west-2). These endpoints correspond to iotDataEndpoint and iotCredEndpoint in your gateway's EffectiveConfig.yaml file located at C:\Program Files\Benchling Gateway\gws\[tenant]\config.

Grant executable permissions

If the above settings (for ports or endpoints) need to be changed on a per-application basis (e.g. if they use a service like Netskope), the applications that need to be granted permissions are:

• greengrass.exe
• java.exe
• python.exe
• aws-iot.exe

Check proxy settings

1. Open Proxy Settings from Windows settings
   
2. Within the Proxy view, check if there is any proxy info
   • If there is a script in the Script Address box (something like http://some-internal-url/wpad.dat), you can put the address in a browser URL box and it will download the config file 
     • Pick the proxy address that corresponds to the lab PC’s location as best as possible and save this information for use during Gateway installation
       

Note: If no proxy settings appear, you may be using different network security software. Proceed to gateway installation.

Gateway supported setups 

There are three supported setups for Gateway installation: 

• The Gateway is installed directly on each instrument computer and the files are accessed locally via the C: drive

• The Gateway is installed on a central Windows File server, that all relevant instrument computers can access

• The Gateway is installed on a domain-joined Windows computer that can access files in a shared network drive 

Gateway installation with Windows installer 

Gateways are created in Benchling and provide installers for the Windows system attached to your instrument. There is one Gateway per instrument PC. This process goes through the phases outlined below: 

• In Benchling, download the Gateway installer 
• On the instrument PC, set up the Gateway

Download the Gateway installer

1. Navigate to Feature settings and select Automation Schemas from the menu
2. Click into Instrument Gateways 
3. Click on the Download Gateway dropdown
   
4. Click on Download Gateway from the dropdown menu to download the installer file (“BenchlingGateway.*-signed.msi”) 
5. Click Generate New Token to download the token file ("Installer_token_file.json") 
   
6. Click Done 

Benchling multi-tenant Gateway setup

You’ll need to perform these next steps on the PC that will host the instrument files. 

1. Double click the BenchlingGateway*.msi file to begin the installation then click Next to continue 
   
2. Accept the terms of the License Agreement and then click Next to continue 
   
3. Accept or change the install path and then click Next to continue 
   
   • If the chosen directory already exists, or if the benchgw_user user already exists, a warning will appear. This may occur if either the directory or user was leftover accidentally from a previous uninstallation 
     
     
4. Select which tenant(s) you want to install. If your network requires the use of a proxy server enter those settings here. The installer will automatically try to verify that it can access benchling.com through the given settings. 
   
5. When you see the message “Network connection successfully verified” click Next to continue 
   
   • Note: The “Will be installed on local hard drive” and “Entire feature will be installed on local hard drive” options are identical. “Entire feature will be unavailable” means that the Gateway will not be installed or will be uninstalled if it previously existed
     
6. On the instrument gateways page, go to the tenant associated with each gateway and download an installer token. The token file contains authentication and expires after an hour
   
7. Upload the installer token, once the token is verified click Next to continue 
   
   
8. Name your Gateway – use a descriptive name to make it easier to identify the instrument used, especially if you will have multiple instruments of the same type that use different Gateways
9. Click Install to complete the Gateway installation, while installing on the PC, you’ll see the pending Gateway installation in your tenant
   
10. When the installation is complete, click Finish 
    
11. When you return to your tenant, the Gateway status should appear as Open if this status does not appear, wait a minute and refresh the page. If it doesn’t show Open within a few minutes get in touch with Benchling Support   
    

When using the installer, make sure that the URL starts with http:// (particularly if you see an error along the lines of “scheme not supported”). Additionally, you may find that even if no username or password is required for the proxy, it still requires something to be set in both fields to succeed. Any text can be entered into these fields, as long as they are not empty. 

Gateway names should include: 

• Tenant used
• Instrument type

• Lab room or location / PC identifier (for local gateways) 

   

Adding (or Removing) Gateways 

To add or remove additional gateways after the initial install (or the upgrade flow described above):

1. Go to the Add or Remove Programs page in the Control Panel 
   
2. Find the Benchling Gateway and click Modify and then click Change 
   
3. Select or unselect desired tenants 
   
4. Installation will proceed as before 
   

Note: any existing gateways will have their names displayed, along with the tenant they came from. If there was a gateway that was migrated from the v1.0 installer, we are unable to display this metadata at this time; instead, it will say “Migrated from single-tenant installation.”

Gateway uninstallation with Windows installer 

These steps are performed on the PC that hosts the instrument files. 

1. Double click the BenchlingGateway*.msi file downloaded from the installation step to begin the uninstallation then click Next to continue 
   
2. Click Remove to remove the existing Benchling Gateway then click Next to continue
   
3. Click Remove to continue then review the *.msi that will be removed from the computer and click Yes to continue 
   
   
4. When the uninstallation is complete, click Finish 
   

Benchling Local Gateway Setup and Network Drive Mapping in Windows Domains

1. Create a domain user for Gateway access

• Create a domain account to run the gateway process (e.g., benchgw_domain_user@corp.benchling.com)
  • Avoid using 'benchgw_user' to prevent a naming conflict
• This account should have read/write permissions to the file share used.
• If a separate file server is used including NAS, ensure it is domain-joined to allow domain-level permissions

2. Add the user to the local security policy

• Grant the domain account the Allow log on locally right via:
  • Local Security Policy > Local Policies > User Rights Assignment
• Since Group Policy Object (GPO) may override local settings, configure this via Group Policy and run: gpupdate /force on the gateway machine

3. Set up shared folders

• On the file server or NAS, configure the shared folder permissions for the domain account
• Allow read (and write if needed) permissions on the shared path
• Join the server/NAS to the domain so it can enforce domain user permissions

4. Configure drive mapping via GPO

• Open Group Policy Management Console (gpmc.msc)
• Edit or create a GPO under the target organizational unit (OU)
• Navigate to:
  User Configuration > Preferences > Windows Settings > Drive Maps
• Create a new Mapped Drive:
  • Location: e.g., \\server\share
  • Drive Letter: Choose an available one (e.g., Z:)
  • Action: Use “Create” or “Update”
  • Label as: Optional custom name
  • Reconnect: Optional
  • Use: %USERNAME% variables as needed

GPO-mapped drives sometimes fail to show up unless a login script (like netlogon) mounts them explicitly. If that happens:

• Consider using a logon script (e.g., .bat or .vbs) as a workaround.
• Alternatively, use UNC paths (e.g., \\server\share) directly in Benchling Gateway connections

5. Connect in Benchling

• In the Benchling platform, configure the connector to use:
  • The mapped drive letter (e.g., E:\) - if working properly, or 
  • The UNC path (\\server\share) - often more reliable

6. Restart the Gateway service and verify that it is running

• Go to Services
• Find the Benchling Gateway [Tenant Environment] service
• Restart the service and wait for one minute
• Right-click the service and select Refresh
• Ensure the service is showing as Running

Troubleshooting

Error 1067: The process terminated unexpectedly

After switching from running the gateway service from the local bench_gw user account to the domain account, you may see the above error message. To find out the root cause, check out the Event Viewer in Windows for details. 

If you’re seeing a permissions error (e.g. Access to the path ‘C:\Program Files\Benchling Gateway\gws\production\logs\greengrass.out.log’ is denied) you may need to update the permissions on the Benchling Gateway folder so that the domain account has write permissions to generate log files.

S3 Cloud Gateway installation

Using the S3 cloud gateway allows your team to leverage cloud-based infrastructure for managing instrument data. This approach is particularly valuable if you're standardizing on AWS or working with cloud-hosted instruments. It also supports scalable ingestion pipelines when data is collected across global lab sites.

1. In Benchling, go to Feature Settings and select Instrument Gateways
2. Click Configure S3 Gateway
3. Enter the gateway name and your S3 bucket name
4. Click Generate Policy to obtain the necessary IAM policy
5. In AWS:
   • Apply the generated policy to your S3 bucket
   • If using role assumption, ensure the correct trust relationships are configured
   • Confirm that object encryption, versioning, and lifecycle policies will not interfere with file access
6. Ensure your bucket structure supports Benchling’s expected folder and file organization
7. Return to Benchling and complete the configuration

Note: This setup enables bi-directional data transfer between Benchling and your S3 bucket. It is well-suited for cloud-hosted instruments or when routing instrument output from distributed sites to a central platform.

Delegate AWS IAM roles for S3 access

For organizations using centralized cloud teams or restricted cloud governance, it’s common to delegate S3 access through role-based IAM permissions rather than direct bucket credentials. Steps for Role Delegation:

1. In your AWS environment, create an IAM role that Benchling can assume
2. Attach the required S3 access policies to this role
3. Define a trust relationship that allows Benchling's AWS account to assume the role
4. Share the ARN (Amazon Resource Name) of this IAM role with your Benchling Solutions Consultant or Customer Success representative

Why Use Delegated Roles?

• Enables secure access without sharing long-lived credentials.
• Complies with enterprise IT policies and simplifies credential rotation.
• Keeps permissions centralized in your cloud operations team.

Note: Reach out to your AWS administrator or Benchling contact for help setting this up.

Monitor Gateway health

Once a gateway is installed, it’s important to ensure it continues running as expected. Ongoing monitoring helps detect interruptions in data flow early and avoids delays in your workflows.

Recommended Practices:

• Periodically check the gateway status in the Connection – Status should read Open.
• Review recent gateway logs if there are signs of delay or failure.
• Set up a regular test file drop (e.g., weekly) to verify the gateway is ingesting files correctly.
• Maintain system health checks on machines hosting the gateway (e.g., monitor memory, storage, and network uptime).

Tip: Consider adding alerts or internal automation to check gateway heartbeat if your infrastructure supports it.

Configure instrument connections

Once the gateway is installed, you’ll need to connect it to your specific instrument(s) so that Benchling knows where and how to ingest data. This step is critical to define how files flow into the system, what formats Benchling should expect, and how to associate files with downstream workflows.

1. Navigate to Connections in Benchling
2. Click to Create new Connection
3. Select type of Connector (e.g. Agilent Gen5)
4. Enter the Connection details, including the gateway, input/output file paths
5. Specify the file extensions and formats your instrument produces
6. Save the configuration

Note: For specific instruments, refer to their respective configuration guides for detailed instructions.

About File objects

When instrument files are ingested through Benchling Connect, they are automatically converted into File objects. These files are not just static attachments—they are structured data objects enriched with metadata and tightly integrated into the Benchling data model. Understanding how files behave in Benchling helps your team search, trace, and reuse data more effectively across workflows.

Key Features:

• Automatically created upon data ingestion
• Associated with metadata for enhanced traceability
• Accessible via Benchling's global search and APIs
• Usable as inputs for runs and analyses

Note: File objects differ from traditional attachments by offering structured data management capabilities.

Supported out-of-the-box Data Connectors

Benchling Connect supports a wide range of instrument vendor softwares to help automate data capture across disciplines. Connecting supported instruments ensures that Benchling can correctly interpret and process the output files they generate, reducing configuration time and minimizing manual errors. Some examples include:

• Capillary Electrophoresis: Agilent TapeStation Analysis
• Cell Counters: Beckman Coulter Vi-CELL BLU, Beckman Coulter Vi-CELL XR
• Flow Cytometry: FACSDiva, FlowJo
• Liquid Handlers: Beckman Coulter BioMek
• Liquid Chromatography: Agilent OpenLabs CDS, Cytiva Unicorn, Waters Empower
• Plate Readers: Agilent Gen5, Molecular Devices SoftMax Pro
• qPCR Systems: Applied Biosystems QuantStudio Design & Analysis, Applied Biosystems QuantStudio RT-PCR
• Surface Plasmon Resonance: Cytiva Biacore T200 Control
• xMAP: Luminex xPONENT, Bio-Rad Bio-Plex Manager

Note: For a comprehensive list and specific configuration guides, refer to Benchling's instrument support documentation.

If an out-of-the-box connector isn’t available, you can also use Connector builder!

Connector builder

Connect Builder is a set of no-code tools for organizing instrument data. It lets you create automated pipelines that take raw data, transform it into a structured format, and load it directly into Benchling.

Connect builder supports:

• Separator-delimited files: .csv, .txt, .tsv
• Excel formats: .xls, .xlsx

To get started, upload an example of your instrument’s output file.

For more help, contact your Benchling Customer Success Manager.

Permissions and access

Managing permissions ensures that only the right users can configure gateways, connect instruments, and interact with ingested files. Properly assigning permissions also helps maintain data integrity and security across teams.

Below is a summary of which roles can perform key Benchling Connect actions:

• Tenant Admins can perform all configuration and management actions.
• Project Admins can manage instrument connections and file visibility within assigned projects.
• Project Members can view and use ingested data but cannot configure gateways.
• Read-Only Users can view file records but cannot take action.

Tip: Check your organization’s Benchling role assignments and folder/project-level permissions to ensure access aligns with responsibilities.

Troubleshooting local Gateway problems 

Another installation is in progress

You may occasionally encounter this error:

If this happens, open Task Manager, find the Windows installer main task, right click and choose End task. Then, run the installer again as before.

At this point, the gateway will have already been created in Benchling. Make sure to archive the gateway on the Instrument Gateways page to avoid confusion.

Download the PC Compatibility Script

Navigate to Feature Settings → Automation Schemas → Instrument Gateways.

In the upper right corner, click the Setup Gateway dropdown button.

From the dropdown menu, select Download PC Compatibility Script.

This action will download the file Compatibility.*.exe to your computer and display the following prompts:

Generate Installer Token

Click Generate New Token to download the token file installer_token_file.json.

Once the download is complete, click the Done button.

Execute the Compatibility Script

The script will now perform a series of checks. Some steps will be fully automated, while others will require user interaction.

To begin, open the Downloads folder and double-click the compatibility script Compatibility.*.exe.

First Set of Verifications

The first few steps are fully automated. If all checks are successful, you should see a confirmation screen similar to the following:

Provide Installer Token

As shown in the previous screenshot, you are now prompted to provide a fresh installer token. You should already have the token file downloaded along with the compatibility script. However, if more than 60 minutes have passed since the token was generated, it has expired, and you will need to download a new one.

Please place the fresh token file in the same folder where the compatibility script is located.

Once you have the valid token ready, return to the script window and press any key.

The script will display a list of available token files in the compatibility script folder.

Use the Up and Down arrow keys on your keyboard to select the correct token file and press Enter. (In the example, the file is installer_token_file (2).json.)

If you do not see the token listed (because it was placed in a different folder), select the last option, Enter path to token manually, and input the full path to the file.

However, we strongly recommend moving the token file to the same folder as the compatibility script, then closing and restarting the script. This approach minimizes the risk of errors related to the file path.

Next Set of Verifications

If you have completed the previous steps correctly, the next set of automated verifications will run, and you will see results similar to the following.

If you did not provide an installer token, some of the connection verification steps will prompt you to manually enter the endpoint address.

While this can be done with assistance from our support team, we strongly recommend downloading a fresh installer token and re-running the script to avoid potential errors caused by manual input.

Failed Verifications

Please note that in the previous screenshot, one of the verification steps failed: the Windows user required for the Benchling Gateway to operate already exists. This occurred because the Gateway Installer was already installed on the example PC.

However, any of the verification steps may fail for various reasons. This tool is designed to help identify and minimize potential compatibility issues early in the Gateway installation process.

If you encounter a failed verification and are unsure how to resolve it, please contact our support team for assistance.

Shared Folder Verification

Please pay attention to the final prompt shown in the screenshot:

Some instruments require data exchange via a shared folder. If your setup involves a shared folder, enter the path to the folder when prompted. The script will then verify whether the folder is accessible from the current PC.

If your setup does not involve a shared folder, you can enter any value and ignore the resulting failure message. Afterward, press n on the keyboard and then Enter, indicating that you do not wish to retry the verification step with another value.

Finalization

After the last verification is completed, you will be prompted to press any key.

Before proceeding, if any of the checks failed, please take a screenshot of the failure messages and contact our support team. This will help us ensure maximum compatibility for your setup.

Once you have saved all the necessary information, return to the script window, press any key, and the compatibility script will close.

Folder Structure

Upon installation, these are the folders and files that should appear in the designated directory. The gws folder contains the gateways themselves, the jdk folder contains the JDK we install, and the installation.manifest contains important metadata, and should not be modified.

Inside of the gws folder are the individual gateways, one folder per gateway.

If an upgrade was performed from a v1.0 gateway to a v1.1 one, there will instead be a primary folder for that gateway, and a primary.manifest file that indicates which type of tenant (production, development, or test) the v1.0 gateway has been mapped to.

For additional troubleshooting of unexpected gateway behavior, please go to the logs directory inside the folder for the gateway in question. The default-adapter and greengrass log files will be most helpful in particular if consulting with the Benchling team. 

Frequently asked questions

Q: What should I do if the gateway status doesn't show as Open?

• Wait a few minutes and refresh the page.
• Ensure the benchgw_user has appropriate directory access.
• If the issue persists, contact Benchling Support.

Q: How do I handle errors related to output directories?

• Verify folder access permissions on the gateway computer.
• Ensure consistent configurations between test and production environments.
• Consult the Benchling Connect Installation Guide for detailed steps.

Q: Can I use Benchling Connect with instruments not listed in the supported instruments?

• Yes, Benchling offers a Connect builder for custom integrations.
• Upload an example output file to get started.
• Contact your Benchling Account Executive for assistance.

Q: How are files managed within Benchling?

• Files ingested via Connect become structured File objects.
• They are searchable, permissioned, and enriched with metadata.
• Files can be used in runs and analyses within Benchling.

Q: What file formats are supported by Benchling Connect’s Connect Builder?

• Separator-delimited files: .csv, .txt, .tsv.
• Excel formats: .xls, .xlsx.
• Other formats may be supported depending on the instrument and configuration.