Connections Configuration & Maintenance

Managing Hosts

For environments using the Gateway architecture, Hosts are the PCs where Gateway executables are installed. The Hosts section of the Connections page allows you to view and manage all Hosts in your environment.

Viewing Hosts

Navigate to the Hosts section in the Connections page to see all Hosts in your environment. Each Host card displays:

• Host Name: The name assigned during Gateway installation
• Status: Current status (Live, Disconnected, or Shutdown)
• Core Version: The version of the Gateway running on the Host
• Connections: Number of Connections running on the Host

Host Details

Click on a Host to view its detail page, which includes:

• Host Information: Name, status, IP address, MAC address, and installation path
• Active Connections: List of all Connections running on this Host
• Host Telemetry: Performance metrics and file processing statistics

Creating Connections on a Host

1. Navigate to the Host's detail page
2. Click
   Create connection on host
3. Choose one of the following options:
   • Create new connection: Select an Agent Template and configure a new Connection
   • Move existing connection: Migrate a Connection from another Host to this one

Moving Connections Between Hosts

To move a Connection from one Host to another:

1. Navigate to the destination Host's detail page
2. Click
   Create connection on host
3. Select Move existing connection
4. Choose the Connection to move from the list
5. Wait for the migration to complete

The Connection will stop on the source Host and start on the destination Host. No data is lost during the migration.

Updating Hosts

Hosts running Gateway version 5.6.0+ can be updated through the Ganymede UI:

1. Navigate to the Host's detail page
2. If an update is available, an Upgrade button will appear
3. Click Upgrade to update the Host to the latest Gateway version
4. All Connections on the Host will be updated simultaneously

Removing Hosts

To remove a Host:

1. Move or delete all Connections on the Host
2. Uninstall the Gateway from the PC using the standard uninstallation process
3. The Host will appear as "Disconnected" and can be removed from the UI

---

Maintaining Agent Templates

Clicking on an Agent Template in the Ganymede web app UI opens up a page displaying the template's configuration. This page allows you to view the configuration, logs, and build history, as well as update the configuration of Connections associated with the Agent Template.

Terminology

Agent Templates are also referred to as "Agents" throughout the UI and documentation. These terms are used interchangeably.

Updating Agents

To modify Agent settings after creation, select the desired Agent Template in the Ganymede web app UI to update the Agent. Upon clicking

Save

, the changes to the Agent Template will be applied to any running Connections based on that Agent Template.

Agents can also be archived or disabled.

Archived Agents cannot be updated, but the Agent's connections can still communicate with Ganymede Cloud. All associated connections for these Agents will continue to run, but the Agent can no longer be modified. Archived agents can be restored to an active state by selecting the desired Agent and clicking on the Restore Agent link.

Disabled Agents cannot be updated and its connections can no longer communicate with Ganymede Cloud.

Updating Connections

To update a Connection, select the desired Connection in the Connections tab and click the

Edit Connections

button. You can update the following fields on a connection from the Ganymede UI:

 

Updating Connections

Every time the Connection contacts Ganymede with a health check-in, Ganymede responds with any changes that the Connection needs to incorporate. There are three level of changes that can occur.

• Core Version Update: The core version corresponds to the underlying Host code developed by Ganymede. These changes are new features or patches applied across all Connections, but each Host manages which core version it is pinned to.
• Agent Template Update: Updated through the Agent Template page or the Agent Template's processor notebook. This configuration applies to all Connections for that Agent. For example, if an Agent that runs flow upon file capture is updated to run a new flow, then all compatible Connections will begin to run the new flow.
• Connection Configuration Update: Updates made to the Connection's configuration will only update a single Connection, rather than the Agent Template that it was generated from. Different Connection-level variables and labels can be configured for Connections associated with the same Agent Template.

There are two types of remote updates that occur based on the type of update - full update or runtime update.

Full Update

Compatibility

• Agents or Hosts running core v4.8.0 or later.
• The core version of the installed connection must align with the major version of the core version of the agent Ganymede's UI. Otherwise, a breaking change requires reinstallation.
• Auto-update is enabled for the agent.

How full updates are initiated

A full update is only triggered for a "Core Version Update." The remote update is not initiated without user intervention.

note

In the Ganymede UI, a Host's core version is listed on the right side of the page in a section called "Core Host Infrastructure." If the host is not up to date to the latest available core version, an "Upgrade" button will appear. The text will inform users what version is available and what version the host is currently pinned to.

Once a user clicks to Upgrade an host, the host will update on its next status ping.

Update Process

A full update is handled by Ganymede seamlessly; as such, after the full update is requested, it is performed for the Host. When Host receives a command to perform a full update, it continues to operate normally while attempting to start the new version in parallel after verifying the validity of the command and the executable. Once the new version registers with Ganymede as operational, the old Gateway stops. The new executable also cleans up the artifacts of the old executable and its dependencies.

There may be a disruption to any ongoing processing on the Agent during the update, so it is safest to request it when no activity occurs on the instruments where the Agent Connections are running.

If the new Gateway fails to start, the old Gateway will resume, and the system will not attempt a full update again on that version to avoid putting the Host in a precarious state.

Runtime Update

Compatibility

• Agents installed with core v1.0.0 or later
• The core version of the installed connection must match the core version of the agent Ganymede's UI
• Auto-update is enabled for the agent

How runtime updates are initiated

Changes in the Agent Template configuration, including the Agent user-defined code, or Connection configuration, will be sent to the Connection on its next status ping as soon as they are saved.

Update Process

A runtime update does not require any process restart or executable reinstallation. As a result, the Connection can accept changes to configuration while continuing normal operations. The update is validated for integrity and the information is stored locally for access if the Connection restarts for any reason.

Viewing Agent History

Viewing Build History (Legacy)

Each iteration of Agent build can be viewed in the History tab of the Agent. This view provides context for each change, either as a log of the configuration change or through a custom commit message from the Agent notebook.

 

Configuration differences between two Agent builds can be viewed for audit or debugging purposes by clicking

button.

 

Viewing Historical Code

The code corresponding to historical commits can be viewed by clicking the

View Code

button. This opens up a modal which allows you to copy the code from the historical commit to the clipboard if desired.

Maintaining Agent Connections

Connection status updates and logs can be accessed in the Ganymede web app UI.

 

Connection data can be viewed by clicking on the appropriate connection card in the Connections tab.

 

This opens up a page displaying parameters associated with the Connection:

Connection Details

Field Name	Description
Status	Current running status of the installed Connection
Recent Activity	Provides links to associated Flows and Files
Agent	Agent associated with the Connection
Connection Version	The version of the Connection configuration currently running, updated when the Connection configuration is modified
Agent Version	The version of the Agent configuration from which the Connection is running, updated when the Agent configuration or processor code changes
Core Version	The version of the core Agent infrastructure from which the Connection is running; requires a reinstall to update
Started At	UTC Time when the Connection was first registered in Ganymede
Last Status Ping	Time when last status ping was received from the Connection by Ganymede
PC Name	Hostname of the machine hosting the connection
MAC Address	MAC address of the machine hosting the connection
Machine IP	IP address that Ganymede sees from the machine hosting the connection
Install Path	Directory path on the hosting machine where the executable was installed on
Service Name	Windows service name for the Connection on the hosting machine

Below the Connection Details box, you'll find Connection-specific configurations:

• Name: Name of the Agent associated with the Connection
• Connection File Tags: Tags placed on files uploaded by the Connection
• Variables: Key-value pairs that can be referenced in user-defined code. These are also used to specify reserved keywords for the Connection, if applicable.
• Labels: Strings that can be used to group Connections in the Ganymede UI
• Emails: Email addresses to notify when the Connection encounters an error. These email addresses are also used by the notify function found in the agent_sdk.

Connection Status

Agents send a heartbeat message to Ganymede Cloud every 30 seconds to inform their status. The status of an Agent can be one of the following:

• Live: The Agent is currently running and communicating with Ganymede Cloud
• Disconnected: Ganymede Cloud has not received a status update from the Agent in the last 65 seconds
• Shutdown: The Agent was intentionally shut down, possibly due to a user shutting down the computer, manually stopping the Agent service, or encountering a known exception.
• Deprecated: The Agent has been disabled in Ganymede UI as described in the Updating Agents section.

Connection Notifications

For Agents v5.1.7+, you can create send email notifications to all subscribers by using the agent_sdk.notify method in your user-defined processor code. For example:

import agent_sdk

def execute(**kwargs) -> Optional[TriggerFlowParams]:  # type: ignore
     # ... code here that checks for some condition
    if(some_condition):
        agent_sdk.notify(f"The file {file_name} is missing an experiment ID")

Viewing Logs

Logs can be found on the Logs tab for each Agent and Connection, and filtered on by both log severity and date. For Agents v4.9+, user-defined log messages can be added by referencing the corresponding agent_sdk method for logging. Descriptions of log messages can be found on the Agent Logs page.

The Instrument tab within the Connection logs page contains downloadable text files for the Connection's logs, enabling you to search over logs locally if desired.

Host Details

Host data can be viewed by clicking on the Host from the listing page or the Host chip.

Field Name	Description
Status	Current running status of the installed Host
Gateway Version	The version of the Gateway exe that is running on the host
Started At	UTC Time when the Host was first registered in Ganymede
Last Status Ping	Time when last status ping was received from the Host by Ganymede
Install Path	Directory path on the hosting machine where the executable was installed on
Service Name	Windows service name for the Gateway exe on the hosting machine
Machine Name	Hostname of the machine hosting the exe
Machine IP	IP address that Ganymede sees from the machine hosting the exe
Machine Architecture	Processor architecture of the host machine
Operation System	OS of the host machine
Running as User	User identity of the Gateway Service

• Emails: Email addresses to notify when the Host encounters an error or has an update in its Host status. These email addresses are also used by the notify function found in the agent_sdk.
  • Send Host Status Email Notifications: When enabled, Ganymede will send an email notification to the specified email addresses when the Host status changes.
  • Connection Offline Alert Timeout (min): The number of minutes that the Host must be offline before an email notification is sent.
  • Send Email Notification on Host Shutdown: When enabled, Ganymede will send an email notification to the specified email addresses when the Host enters a shutdown state.

Uninstalling Agent Connections

Windows

A Host can be uninstalled and its associated service removed through the “Add or Remove Programs” panel from the Control Panel.

 

After uninstalling the Gateway, the Ganymede folder will remain in the Program Files directory. You can also run the unins000.exe file in the installation folder to remove the Gateway and all other previously installed versions.

warning

By default, the installation directory of the Gateway is retained, so that logs associated with the Gateway are kept on the instrument PC. Removing the Ganymede folder will also remove these logs.

info

If the Gateway service continues to appear in the Services panel after uninstalling the Gateway, you can remove it by running the following command in the Command Prompt:

sc delete <service_name>

Linux

To uninstall the Gateway, stop the systemd service associated with the Gateway and remove the service file from /etc/systemd/system/.

# to stop the Agent Connection service
sudo systemctl stop ganymede_example_agent.service

# remove the service file
sudo rm /etc/systemd/system/ganymede_example_agent.service