runai-bgu Interactive Subshell for Workspaces

Introduction

The runai-bgu CLI automatically opens a subshell when you submit interactive workspace workloads like X11 and SSH workspaces. A subshell is a customized bash environment that provides a seamless interface for working with your remote workspace, complete with special aliases, a custom prompt, and automatic cleanup features.

This page explains what subshells are, how to recognize them, what features they provide, and how to work with them effectively.

What is a Subshell?

A subshell is a child bash process that runs within your current terminal session. When you submit interactive workloads (such as pycharm, vscode, stata, or sumo), runai-bgu automatically:

  1. Sets up port forwarding to your workspace

  2. Creates a temporary configuration file with custom aliases and settings

  3. Launches a new bash shell with this configuration

  4. Provides you with an enhanced terminal environment for interacting with your workspace

The subshell acts as a bridge between your local environment and the remote workspace, making it feel like you’re working locally while actually connecting to a containerized environment on the cluster.

Workload Types That Use Subshells

Subshells are automatically created for the following interactive workload types:

SSH Workspaces

  • pycharm - PyCharm IDE workspace

  • vscode - Visual Studio Code workspace

X11 Workspaces

  • stata - Stata statistical software

  • sumo - SUMO traffic simulation software

These workload types inherit from SSHWorkspace or X11Workspace classes and automatically establish SSH connections with port forwarding.

How to Recognize You’re in a Subshell

When runai-bgu opens a subshell, you’ll notice several visual indicators:

Custom Prompt

Your bash prompt changes to clearly indicate you’re in a Run:AI interactive session:

(Run:AI interactive job: my-workspace) user@hostname:~->

The prompt includes: - Blue-colored text indicating the interactive session - The name of your workspace - A distinctive arrow (→) at the end

Setup Messages

When the subshell starts, you’ll see messages like:

SSH workspace my-pycharm is running. Setting up port forwarding to port 12345...

This indicates that port forwarding has been established and the subshell is ready.

Available Features in the Subshell

The subshell provides several convenient features and aliases:

Built-in Aliases

stop

Exit the subshell and return to your normal terminal.

(Run:AI interactive job: my-workspace) user@hostname:~-> stop
stop-all or stopall

Delete the workspace and exit the subshell in one command.

(Run:AI interactive job: my-workspace) user@hostname:~-> stop-all

This runs runai workspace delete my-workspace and then exits.

Workload-Specific Aliases

Some workloads provide additional custom aliases:

Stata Workspace

xstata-mp

Launch Stata with X11 forwarding directly from the subshell.

(Run:AI interactive job: stata-work) user@hostname:~-> xstata-mp

SUMO Workspace

sumo-gui

Launch the SUMO graphical interface with X11 forwarding.

(Run:AI interactive job: sumo-sim) user@hostname:~-> sumo-gui

Automatic Cleanup

The subshell includes automatic cleanup mechanisms:

  • When you exit the subshell, port forwarding processes are automatically terminated

  • Temporary configuration files are cleaned up

  • Background processes are properly killed to prevent resource leaks

Connecting and Reconnecting

Initial Connection

When you submit an interactive workspace, the subshell opens automatically:

$ runai-bgu submit pycharm -n my-pycharm --cpu 4 --memory 8Gi
SSH workspace my-pycharm is running. Setting up port forwarding to port 12345...
(Run:AI interactive job: my-pycharm) user@hostname:~->

Reconnecting to Existing Workspaces

To reconnect to an already running workspace, simply run the same submit command again:

$ runai-bgu submit pycharm -n my-pycharm --cpu 4 --memory 8Gi

The CLI will detect that the workspace is already running and: - Skip the job creation step - Wait for the workspace to be ready (if it’s still starting) - Set up new port forwarding - Open a fresh subshell connection

This allows you to: - Reconnect after network disconnections - Open multiple terminal sessions to the same workspace - Resume work after closing your previous session

Working in the Subshell

Multiple Sessions

You can open multiple subshell sessions to the same workspace by running the submit command multiple times in different terminals. Each session gets its own port forwarding and can work independently.

Port Forwarding

The subshell automatically manages SSH port forwarding: - A random local port is selected and forwarded to port 2222 in the container - The port number is displayed when the connection is established - Port forwarding remains active for the duration of the subshell session

File System Access

From within the subshell environment, you can: - Access your workspace’s file system - Transfer files between local and remote environments - Use standard Unix tools and commands - Install additional software in the container (if permissions allow)

Troubleshooting Subshells

Port Forwarding Issues

If port forwarding fails:

Check workspace status
$ runai-bgu describe my-workspace
Verify the workspace is running
$ runai-bgu list
Try a different port
$ runai-bgu submit pycharm -n my-workspace --port-override 12345

Connection Problems

If the subshell doesn’t start properly:

  1. Ensure your workspace is in "Running" status

  2. Check your network connectivity to the cluster

  3. Verify your authentication session is active with runai-bgu login

  4. Try submitting the workspace again

Exiting Cleanly

Always exit the subshell properly using: - stop command - exit command - Ctrl+D

Avoid killing the terminal or process forcefully, as this may leave port forwarding processes running in the background.

Best Practices

Use descriptive workspace names

Choose clear, descriptive names for your workspaces to easily identify them in the subshell prompt.

Keep sessions organized

When working with multiple workspaces, use different terminal windows or tabs to keep subshell sessions organized.

Clean up when done

Always use stop-all or properly delete workspaces when you’re finished to free up cluster resources.

Monitor resource usage

Use runai-bgu describe to monitor your workspace’s resource consumption while working in the subshell.

Save your work

Remember that the container file system is ephemeral. Save important work to mounted volumes or transfer files to your local system.

Advanced Usage

Custom Environment

The subshell inherits your local environment variables and bash configuration, while adding workspace-specific features. You can:

  • Set additional environment variables in the subshell

  • Install additional tools (if the container allows)

  • Customize the working environment for your specific needs

Integration with IDEs

For IDE workspaces (pycharm, vscode), the subshell serves as a control interface while the actual IDE connects separately:

  1. The subshell manages the connection and provides control commands

  2. Your IDE connects to the workspace through the established port forwarding

  3. You can use the subshell for terminal operations while the IDE handles code editing

This provides a complete development environment with both graphical and command-line interfaces.