Skip to content

Create a Custom Linux Workspace

Beginner 15 minutes Auto-generated screenshots

Overview

In this tutorial, you'll learn the complete lifecycle of creating a custom Linux workspace on the RosettaHub Supercloud platform: clone a formation, launch it, customize the environment, snapshot it into a reusable image, and share it with others. By the end, you'll have a personalized Ubuntu workspace that anyone you share it with can launch in minutes.

Formations are cloud-agnostic IaC recipes that combine cloud keys, images, instance types, and configuration into a single deployable unit. When you launch a formation, RosettaHub creates a session containing one or more running machines.

Prerequisites

  • [ ] RosettaHub account with active subscription
  • [ ] At least one cloud account connected (see Cloud Keys)
  • [ ] Access to the Ubuntu Server 22.04 public formation
  • [ ] An SSH client installed (Linux/Mac: built-in terminal; Windows: PuTTY)

Steps

Step 1: Open the Workspaces and Labs Perspective

From the RosettaHub dashboard, select the Workspaces and Labs perspective. This organizes your view to show Cloud Formations, Sessions, and related panels.

In the Cloud Formations panel, locate the Ubuntu Server 22.04 formation.

Step 2: Clone the Formation

Right-click Ubuntu Server 22.04 and select Clone. In the dialog that appears, name your new formation my-ubuntu.

Tip

Cloning creates your own private copy of the formation. You can modify it freely without affecting the original.

Step 3: Launch Your Workspace

Click on your new my-ubuntu formation. A launch confirmation dialog appears -- click Yes to deploy.

Your session appears under the Sessions panel. Wait for the status indicator to show a green tick, which means your machine is ready.

Note

Provisioning typically takes 1-3 minutes depending on the cloud provider and region.

Step 4: View Connectivity Information

Click on your running session to view its connectivity details. The panel displays:

  • SSH connection string (host, port, username)
  • PEM file download (for Linux/Mac SSH clients)
  • PPK file download (for PuTTY on Windows)

Step 5: Connect via SSH

Connect to your workspace using SSH.

Linux / Mac:

chmod 400 ~/Downloads/my-ubuntu.pem
ssh -i ~/Downloads/my-ubuntu.pem ubuntu@<your-machine-ip>

Windows (PuTTY):

  1. Download the PPK file from the connectivity panel
  2. Open PuTTY and enter the machine IP address
  3. Navigate to Connection > SSH > Auth and browse to the PPK file
  4. Click Open to connect

Tip

For file transfers on Windows, use WinSCP with the same PPK file for authentication.

Step 6: Customize Your Environment

Install any software you need. For example, install Emacs:

sudo apt update
sudo apt install emacs -y

Verify the installation:

emacs --version

You can install any packages, configure system settings, add users, or set up development tools -- you have full root access.

Step 7: Create a Machine Image

Once your customizations are complete, snapshot your session to preserve them as a reusable image.

  1. Right-click your running session
  2. Select Create Machine Image
  3. Keep Update Originator Formation On Success checked

RosettaHub will:

  • Snapshot the current state of your machine into a new machine image
  • The new image appears under the Images panel (see Images Guide)
  • Automatically update the my-ubuntu formation to use the new image

Note

The next time you or anyone else launches this formation, it will include all the software and configuration you installed.

Step 8: Share Your Formation

Share your customized formation with others:

  1. Right-click the my-ubuntu formation
  2. Select Share
  3. Choose to share with a specific user, your organization, or a group

Recipients can launch your formation and get an identical environment with all your customizations pre-installed.

Step 9: Shut Down Your Machine

When you are finished working, shut down the machine to stop compute costs.

  1. Right-click your running session
  2. Select Shutdown

Warning

Running machines incur hourly compute costs. Always shut down machines when you are not actively using them. After shutdown, only image storage costs remain.

Next Steps

Troubleshooting

Session stuck at pending or creating status

This may indicate:

  • Cloud provider quota limits reached
  • Region availability issues
  • Budget allocation exceeded

Check your cloud account status and region settings, or contact your organization administrator.

Cannot connect via SSH

Ensure that:

  • The session shows a green tick (fully provisioned)
  • You downloaded the correct PEM/PPK file for this session
  • Your PEM file permissions are set to 400 (Linux/Mac)
  • Your network allows outbound SSH traffic on the required port
Clone option is not available

You may lack permissions to clone the formation. Verify that:

  • You have an active subscription
  • The formation is shared with you or is publicly available
  • Your organization policy allows formation cloning
Create Machine Image fails

The snapshot process may fail if:

  • The machine is in a transitional state (starting, stopping)
  • Cloud provider limits on the number of images have been reached
  • There is insufficient storage quota

Wait for the machine to reach a stable state and try again.