> For the complete documentation index, see [llms.txt](https://docs.rhinofcp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rhinofcp.com/creating-and-running-code-objects/creating-and-running-interactive-container-code.md).

# Creating and Running Interactive Container Code

## What is an Interactice Container Code Object?

Interactive Container Code lets you run pre-built container images with interactive apps or graphical interfaces. You can use tools like Jupyter Notebooks directly on your on-premises data while keeping that data secure.

### Key Attributes of Interactive Container Code

* **Interactive GUIs:** Unlike other Code Objects, Interactive Containers enable you to execute containers with interactive graphical user interfaces. This facilitates real-time interaction and data visualization within the FCP environment.
* **On-Premises Interaction:** Interactive Containers offer the capability to interact with on-premises data while leveraging the computational power of the FCP. This integration is particularly useful for scenarios where data remains within internal networks.
* **Third-Party Applications:** With Interactive Container Code Objects, you can run third-party applications that are containerized and can be executed within the FCP ecosystem, with no need to install them at each site.

{% hint style="info" %}
NOTE: This capability is limited to third-party applications that can run within a single Linux-based container with no internet connectivity.
{% endhint %}

### Use Cases of Interactive Containers

* **Real-Time Data Exploration:** Utilize interactive visualizations and tools to explore and analyze on-premises healthcare data within the FCP ecosystem.
* **Third-Party Applications:** Run containerized third-party applications such as medical image annotation tools or specialized analysis software.
* **Collaborative Workshops:** Conduct collaborative workshops or training sessions that involve hands-on exercises and interactive activities.

### Benefits of Interactive Containers

* **Interactive Experience:** Gain the ability to interact with GUIs and applications in real-time, fostering dynamic exploration of your data.
* **On-Premises Compatibility:** Execute containerized applications on your on-premises data while utilizing the computational resources of the FCP.
* **Secure Collaboration:** Enable secure collaboration by running third-party tools and applications within the FCP environment, ensuring data privacy.

### Summary

In summary, Interactive Containers offer an innovative pathway to engage with interactive graphical interfaces and applications within the Rhino FCP. By merging on-premises data with containerized interactivity, you can delve deeper into data exploration, collaboration, and visualization while maintaining the highest levels of security and privacy.

## Creating New Interactive Container Code

{% stepper %}
{% step %}

#### Go to the main project's page and select your project.

{% endstep %}

{% step %}

#### Select **Code** from the menu on the left to open the **Code Objects** page.

![](/files/25e46c437b1e4113f2f321899c84b30fb8582689)
{% endstep %}

{% step %}

#### Select the **Create New Code Object** button to open the **Create New Code Object** page.

![](/files/436c8ef3ec8c7bb4965930b87ae69bad36d806c0)
{% endstep %}

{% step %}

#### Select the Interactive Container as the Code Object Type.

The page changes to show the fields needed for this object type.

![](/files/6e8ad1ef664554a529271562a8e57abb3cbc14c4)
{% endstep %}

{% step %}

#### Enter information in the following fields.

*Before you enter information in the fields (see table below), read the following about input and outputs*

*Code objects usually require that you know the number of inputs and outputs your code needs. Those inputs and outputs are provided as data schemas. For example, if your code splits one dataset into two (like a train/test split), you will have to create a code object with one input schema and two output schemas. For more detail into how to structure your code to run on FCP, see* [*Accessing your datasets in Code Objects*](/creating-and-running-code-objects/accessing-your-datasets-in-code-objects.md)*.*

*Multiple input and output datasets are supported in Python, Generalized, and Interactive Container Code Objects. While NVFlare Code Objects do not support multiple datasets, they can still be used as before for learning and inference across multiple sites.*

{% hint style="info" %}
**Pro-tip:** If you don't need this level of control, you can:

* **\[NEW]** set any input or output as optional, which will allow to provide or generate no datasets respectively
* **\[NEW]** set any input or output as a list, which will allow to select 1 or more datasets
* **\[NEW]** select "ANY" as input schema, which will allow code object re-use across any input dataset schema.
* let the system automatically determine the output schemas with [Auto-Generated Data Schemas](/data-schemas/auto-generated-data-schemas.md).
  {% endhint %}

<table><thead><tr><th width="264.5390625">Field/Button</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Indicates the name you want to provide for the code object.</td></tr><tr><td>Description</td><td>Provides a brief summary of what the code object does.</td></tr><tr><td>Input (including three-dot menu items)</td><td>Indicates the file(s) needed for the code object to run properly. Your selection here will affect which Dataset(s) can be selected as input when triggering a Code Run with this Code Object. You can enter one or more input files, such as schemas, configuration files, or others. File(s) can be in DICOM, JSON, and or text formats.<br>- If your input doesn't require a schema, select Any.<br>- Select the Add button to the right of the input entry to add another input. You can add as many as you like.<br>- If your input includes more than a single dataset, select the three dot menu to the right of the Input field, then select Input is a list.<br>- If the input is optional, select the three-dot menu to the right of the Input field, then select Optional Input.</td></tr><tr><td>Output</td><td>Indicates the output file(s) produced when the code object run. You can enter one or more output files. Files can be in DICOM, JSON, and or text formats.<br>- You can also select the option to <em>[ Auto-generate Data Schema from Data ]</em>. For more information about Auto-generating Data Schemas, please refer to <a href="/spaces/ydySyCBmy6F7NnGn4bPa/pages/ef1a475d9abe6e933667e507fc5e0b5df2354cb9">Auto-Generated Data Schemas</a>.<br>- Select the Add button to the right of the output entry to add another output. You can add as many as you like.<br>- If your output includes more than a single dataset, select the three dot menu to the right of the Output field, then select Output is a list.<br>- If the output is optional, select the three-dot menu to the right of the Output field, then select Optional Output.</td></tr><tr><td>Container</td><td>Specifies the name of the Docker container you would like to execute when running this Code Object. This will either be a container image created by someone from your workgroup that is available on your ECR or an image provided by Rhino. If you need a refresher on pushing containers to your ECR, please refer to <a href="/spaces/ydySyCBmy6F7NnGn4bPa/pages/57d8d7e9c30e836f2cda68ed9205249d9633e871">Pushing Containers to the ECR</a>.</td></tr></tbody></table>
{% endstep %}

{% step %}

#### After you've completed your details, you can choose to set required compute resources.

If you want to do this, see Setting Required Compute Resources (Autoscaling).
{% endstep %}

{% step %}

#### Select the Create New Code button to create the new Code Object.

{% endstep %}

{% step %}

#### The Code Object appears in the Code Object page.

When you have completed adding all your Interactive Container *Code* details, click the **Create New Code** button to create your new *Code Object.*
{% endstep %}
{% endstepper %}

### Setting Required Compute Resources (Autoscaling)

{% hint style="info" %}
NOTE: This feature is only available if you are running on the Google Cloud Platform (GCP). *For NVFlare code objects and code runs, you can adjust autoscaling methods for both the NVFlare Server and the NVFlare Client. For the NVFlare Server, you can only specify the CPU and RAM.*
{% endhint %}

Autoscaling allows Rhino to run Code Runs on additional compute resources when the default Rhino Client capacity is not sufficient. This capability is designed to support resource‑intensive, "bursty"(processing tasks occur in short, intense or irregular spurts), or GPU‑based workloads while improving isolation, reliability, and cost efficiency. With autoscaling enabled, Rhino provisions temporary cloud VMs on demand, executes workloads on those VMs, and automatically terminates them when execution completes. This can help you make more efficient use of your computing resources and save on costs.

In this section of the screen there are three options: Use Client Resources, Set Minimum, and Use VM Pool.

<figure><img src="/files/GFBA6RaRsa2CcbnjNlEN" alt=""><figcaption></figcaption></figure>

* **Use Client Resources** - Uses the available client settings and resources.
* **Set Minimum** - Allows you to set the minimum number of resources that must be available. If you choose the Set Minimum option, you can indicate the minimum number of CPUs, amount of RAM, the disk size (VRAM), as well as the type and number of GPUs. You can adjust these settings when you create a code object and also when you run your code. Note that adjustments do not persist and will need to be reset with each run.
* **Use VM Pool** - Allows you to select a Pre-allocated Virtual Machine Pool. Select a VM pool to indicate which dedicated compute resource you want to use for your code run, ensuring guaranteed availability for high-demand workloads such as GPU-intensive AI training and inference. This feature provides faster job startup times by using pre-warmed VMs and offers predictable costs through fixed capacity reservations.

Each option is detailed below.

#### *Use Client Resources*

To use client resources, complete the following steps.

1. Select the Use Client Resources button. It should be selected by default.
2. When complete, select Create New Code Object or start a Code Run.

#### *Set Minimum*

To set the minimum required compute resources, complete the following steps.

1. In the Required Compute Resources section, select Set Minimum.
2. Next, make changes to the settings as needed. Note that these setting changes do not persist the next time you run the code object or code run. The settings are explained below.

|           |                                                                                                     |                                                                                                                                                                                                                           |
| --------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Setting   | Description                                                                                         | Usage Notes                                                                                                                                                                                                               |
| CPU MIN   | The minimum number of CPU cores on which your code will be run.                                     | If the CPU MIN is too low, you might see slow code execution or throttling.                                                                                                                                               |
| RAM MIN   | The minimum amount of RAM (main memory) that you want to allocate to running your code.             | If this is too low, you might see an out-of-memory crash or slowness in execution due to disk swapping.                                                                                                                   |
| DISK SIZE | Amount of storage allocated to the instance.                                                        | Increasing this setting increases capacity (not necessarily speed)                                                                                                                                                        |
| GPU TYPE  | The model of GPU hardware. The number of GPUs indicate the number of GPUs attached to the instance. | If your code isn’t written to use multiple GPUs, extra GPUs might not be used. Note that GPU availability depends on the selected cloud region, Project‑level GPU quotas, and the current capacity at the cloud provider. |

#### *Use VM Pool*

To select a VM Pool, complete the following steps.

1. If you choose Use VM Pool, available pools are shown. For each pool you will see a name, as well as the current resources available. For each pool you will see the following information.

* Number of VMs (if any)
* Number of vCPUs per VM
* Amount of RAM per VM
* Disk size per VM
* Whether there are GPUs available, and how many

2. Select the pool of your choice.
3. When complete, select Create New Code Object or start a Code Run.

## Viewing a Code Object's Configuration

To get an object's configuration, make sure you are on the page containing the original object you would like to view the configuration of. In the box where your original object is, there should be a row for each version. Navigate to the version you would like to view the configuration for and select the three-dot menu button, shown below:

![](/files/903f8d8b02de3537a785b7355db65dd33f4bf44c)

The menu button is on the right-hand side of the row, click it to view a new menu. The new menu should have an option to show that object's configuration, click on that to see the object's configuration.

For Code Objects and Code Runs, if you chose the Use VM Pool option, you will use the pool that was indicated during the Code Object or Code Run configurations.  Selecting this option shows the resources, including the number of VMs and vCPUs that will be allocated, as well as the amount of RAM, the size of the disk, the number of GPUs, the GPU type/mode&#x6C;*,* and the amount of VRAM.

## Creating a New Interactive Container Code Version

1. Go to the page that has the original object you want to create a new version of.
2. In the upper right corner of the box where your original object is, select the **+ New Version** button.
3. A new window appears that allows you to create a new version of your object.

## Removing a Code Object

To remove a code object, complete the following steps.

{% stepper %}
{% step %}

### Open the Code Objects page

Go to the page that lists your code objects.
{% endstep %}

{% step %}

### Find the code object version

If needed, use the search fields at the top right.

* Use **Search Name** to search by code object name.
* Use **Search Description** to search by code object description.

Each code object appears with a row for each version. Find the version you want to delete.
{% endstep %}

{% step %}

### Open the menu for the version

Select the three-dot menu on the right side of the version row, shown below.

![](/files/e30ab6c50f33a01039109108a719df8152c5cb07)
{% endstep %}

{% step %}

### Remove the code object version

Select **Remove code object**.

Repeat these steps for each version you want to remove. When you delete the last version, the code object is fully deleted.
{% endstep %}
{% endstepper %}

To run interactive container code, you'll need to go to the Code Objects page, then fill out the run details.

## Running Interactive Container Code

Create an Interactive Container code object before you complete these steps.

{% stepper %}
{% step %}

#### Go to the main project's page and select your project.

{% endstep %}

{% step %}

#### Select **Code** from the menu on the left to open the **Code Objects** page.

![](/files/bf679f24c6bf45b669f4fcbff3ce49f3888acaa3)
{% endstep %}

{% step %}

#### Select the Run button for the code object you'd like to run.

{% endstep %}

{% step %}

#### In the Run Settings page, specify the Input Dataset(s).

This is one or more Datasets to be used as input to your Code Run. If multiple Datasets are selected, each will be run separately. If a Dataset happens to be a collaborator's Dataset, the code will be run on that collaborator's Rhino Client. In other words, the data never moves outside your collaborator's Rhino Client.

{% hint style="info" %}
Interactive containers require Secure Access to be enabled on the input dataset. For more information about Secure Access, please refer to [What is Secure Access?](/secure-access/what-is-secure-access.md)
{% endhint %}
{% endstep %}

{% step %}

#### Add the Output Dataset Name Suffix.

A suffix that is appended to the name of each input Dataset to define the name of the output Dataset that will be created during your Code Run.
{% endstep %}

{% step %}

#### Indicate the Timeout in Seconds.

The number of seconds that must elapse before a Code Run is automatically killed. This is to avoid zombie tasks that run perpetually within a Rhino client.
{% endstep %}

{% step %}

#### Specify the Run Parameters (Optional).

Here you can paste a JSON object that defines additional parameters to be provided to your Code Run. This can be used for specifying hyper-parameters for *model* validation or any parameter provided to the code. Run parameters are made available to the container code in a file located at `/input/run_params.json`.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Files that you want to run at run-time should be uploaded to the Rhino Orchestrator.
{% endhint %}

To add run time files to your code run, select the run time files from the list of the workgroup run files that appears. You will want to only include the ones you need for the code run, like in the example that follows.

![](/files/1b0e5b57cbafc7752eee0d12284598b17e92d959)

{% hint style="info" %}
Your workgroup run time files include both published and unpublished files. Files from other workgroups only include the files that they have published and have made visible to you and others in your workgroup that share the same persona. For collaborators to have access to files, they must be published. See [Managing Run Time Files](/creating-and-running-code-objects/managing-run-time-files.md) to learn how to publish run time files.
{% endhint %}

When you have completed adding all your Code Run details, either set the required compute resources by following the instruction in **Setting Required Compute Resources (Autoscaling)**, or click the **Run** button to run your code.

## Reviewing Code Run Logs

Logs that are produced during a Code Run can be viewed by clicking on the Status link in the Code Runs view. If you need to search for a specific code run, use the text boxes located at the top right corner of the page. To search by name enter the full name or part of the name in the Search Name text box. To search by description, enter part of the code run's description in the Search Description text box.

![](/files/b9eac61eb5020042cd8f173ca83e2714a1f39575)

Clicking the Status link will open the Logs view for a particular run:

![](/files/913042c4d818bc668909f24d9376bea0c453f1c8)

Logs can be accessed while the Code Run is active and after the Code Run has completed. While the code is running, an auto-refresh option is available.

This Logs view provides the following information:

* General Info - information about the Code Run, including
  * Code Object name and type
  * Code Object version
  * Code Object description
  * Input and Output Datasets
  * Code Object configuration
  * Code Run configuration
* System Logs
  * Errors or warnings that occurred from the FCP side, e.g. Dataset import errors.
* FL server logs (for NVIDIA FLARE runs)
* FL client logs (for NVIDIA FLARE runs)
  * Each federated client's logs will appear separately
* Client-specific logs (for all other run types)

### Troubleshooting Code Runs

**Error Message that Usage Limit Has Been Exceeded**

If you get an error message indicating that the usage limit has been exceeded, your administrator has set usage limits on the number of input rows a workgroup can process per model within a certain timeframe. Getting this message means that the entire run has been cancelled. Please contact your administrator for more details and help with resolving the issue.

## Viewing a Code Run's Configuration

To get an object's configuration, make sure you are on the page containing the original object you would like to view the configuration of. In the box where your original object is, there should be a row for each version. Navigate to the version you would like to view the configuration for and select the three-dot menu button, shown below:

![](/files/903f8d8b02de3537a785b7355db65dd33f4bf44c)

The menu button is on the right-hand side of the row, click it to view a new menu. The new menu should have an option to show that object's configuration, click on that to see the object's configuration.

For Code Objects and Code Runs, if you chose the Use VM Pool option, you will use the pool that was indicated during the Code Object or Code Run configurations.  Selecting this option shows the resources, including the number of VMs and vCPUs that will be allocated, as well as the amount of RAM, the size of the disk, the number of GPUs, the GPU type/mode&#x6C;*,* and the amount of VRAM.

## Deleting a Code Run

Follow these steps to delete a code run.

{% stepper %}
{% step %}

### Open the Code Runs page

Go to the page that lists your code runs.
{% endstep %}

{% step %}

### Find the code run

If needed, use the search fields at the top right.

* Use **Search Name** to search by code run name.
* Use **Search Description** to search by code run description.

Find the code run you want to delete.
{% endstep %}

{% step %}

### Open the menu for the code run

Select the three-dot menu on the right side of the row, shown below.

![](/files/d6d3efbded53ff3765ccd54d866cfef8630e6c3c)
{% endstep %}

{% step %}

### Remove the code run

Select **Remove code run**.
{% endstep %}
{% endstepper %}

## Running an iGC (Interactive Container) and Accessing Workspace Files

Interactive Containers allow you to run entire containerized applications such as Jupyter Notebook (and not just containerized code) remotely and interact with them. You can use Jupyter Notebook, QuPath, 3D Slider, R Studio and LibreOffice. R Studio and LibreOffice require more custom setup information: if you choose to use them, please contact us for help.

An Interactive Container similar to connecting to a remote desktop, but you do not have the ability to exfiltrate any data. (This is governed by permissions policies, requires approval from the data owner, and is logged and auditable.)

### Running an Interactive Container

{% stepper %}
{% step %}

#### In the Code Runs page, select a code run that has the row of type "iGC" and shows a status of "Running".

{% endstep %}

{% step %}

#### Connect to the active session by clicking the arrow icon.

It appears under the Type column for interactive container entries.

![](/files/e96056c05514c97a7d91ce6bc7b3f1a1e301c8a8)
{% endstep %}

{% step %}

#### A new tab opens with the interactive session.

This tab runs your Interactive Container on the remote client.
{% endstep %}

{% step %}

#### Click the desktop icon and interact with the application as you would normally.

![](/files/640c853eda50a558f05e64000033ec56a2acb286)
{% endstep %}
{% endstepper %}

### Working with Files in the Workspace Folder

In your interactive session, files such as code run outputs are stored in the `/workspace` folder, by default. This folder keeps your work saved across multiple interactive sessions, so you don’t have to manually save and import files as input/output datasets.

{% stepper %}
{% step %}

#### If you are unfamiliar with the Rhino FCP Workspace, review the steps below before continuing.

{% endstep %}

{% step %}

#### Navigate to the `/workspace` folder using the file explorer or navigator for your iGC platform.

If you performed a code run, results are stored, by default, in this folder.
{% endstep %}

{% step %}

#### If you do not want the files to be overwritten, copy them in another folder so that you can interact with them.

Note that if you overwrite a file in the `/workspace` folder, the changes will be in any other Interactive Container session that you have running (provided it is under your account and it is in the same workgroup).
{% endstep %}
{% endstepper %}

### Importing a Tabular File

There are a few ways to import a tabular file to an Interactive Container. With the Interactive Container running:

* Save the tabular file as `/output/dataset.csv`.
* Or, after you have saved all your files, click the desktop icon named Create Output Dataset. This will run a local script that looks for files under `/output/file_data/` and populates a new `/output/dataset.csv`file with the file names so they can be imported as a Dataset.

When you terminate the interactive session, the FCP will attempt to import the output Dataset defined in the `/output/dataset.csv` file. If you did not create this file, the Code Run will show an “Error: failure to import dataset” message.

### Exporting Files from the Workspace Folder

To extract files from your `/workspace` folder to a location outside the Rhino Client, follow these steps:

{% stepper %}
{% step %}

#### Copy to Output

Within your interactive session, copy the desired files from `/workspace` into an output dataset directory (e.g., `/output/0/file_data`).
{% endstep %}

{% step %}

#### Import as Dataset

Import these files as a formal Rhino dataset. For more information on how to do this, [Importing and Exporting Datasets to and from Your Network Storage](/getting-started/quick-start-guide/importing-and-exporting-datasets-to-and-from-your-network-storage.md).
{% endstep %}

{% step %}

#### Export to Storage

Export that dataset to client-mounted storage or to `/rhino_data`. For more information on how to do this, see [Importing and Exporting Datasets to and from Your Network Storage](/getting-started/quick-start-guide/importing-and-exporting-datasets-to-and-from-your-network-storage.md).
{% endstep %}
{% endstepper %}