Skip to main content

Importing Practical Machines

Lab Builder lets you import virtual machines from your own AWS environment using Amazon Machine Images (AMIs) you've shared with Immersive.

Adding a Virtual Machine

Lab Builder lets you import VMs from your environment to use in labs. We currently support provisioning machines from Amazon Machine Images (AMIs) you've shared with us.

Your AMIs must be created in your own AWS account. This lets you build and manage your images in your own AWS account.

Before adding a Virtual Machine, you must share your AMI with Lab Builder.

Note: Do not add sensitive material — such as credentials, private keys, or proprietary data — to machines you import into Lab Builder.

  1. From the navigation bar, click Manage > Create Lab.
  2. At the top of the Lab Builder Dashboard, click + Create a new custom lab.
  3. On the left-hand Lab properties panel, click Add system.
  4. To add your own AMI, click Add on the Virtual Machine – EC2 option. 

    This adds a machine with default settings and loads a placeholder AMI.
  5. To edit the machine, click the Edit button. A new page appears where you can configure the settings for this machine.

Configuring Machine Settings

System Name

The System Name appears in the lab next to the IP address the machine is assigned. Give it a name that's useful for your lab briefing panel and tasks — for example, "Web Application machine" makes it easy to reference in task questions like "which ports are open on the Web Application machine?"

Machine Configuration

This section lets you configure your AMI and machine size. It also displays the AWS account and region you need to share your AMI with.

  • AMI ID: This is the AMI ID of the AMI you hare shared with the Immersive AWS Account.
  • Instance Type: This is the instance size for the machine when it is started on our platform as part of a lab. Lab Builder currently only supports t3.micro, t3.medium, and t3.large. We recommend using one of these instance types when building your AMI to ensure it works on these types of machines.

Connection Type

Within Immersive, machines can drop users straight into a session via SSH or RDP. We can also embed web apps too so they are rendered in their own frame in the lab.

  • None: This would typically be used for a machine you don't wish to display as a Desktop tab in a lab. For example, if you have built a vulnerable machine and want users to attack it in a lab, you would select None for the connection type. This will still show the IP address of the machines in the systems tab, but it won't have its own connection tab in the Lab.

  • SSH: This allows an SSH session to be opened into the machine automatically in a tab when the lab loads. We do not support SSH keys and only support connections via username and passwords. Ensure that you configure your SSH agent to accept these types of connections.

  • RDP: This allows an RDP session to be opened automatically in a tab on the lab when the machine loads.
  • HTTP: This automatically opens a tab in the lab that embeds an application that can be run on a machine. The application must support HTTP and will need to be listening on port 80.

Sharing your AMI with Lab Builder

To import your AMI into Lab Builder, you need to share it with us. The machine configuration page — which you see when you click Edit on a virtual machine — displays the account you need to share your AMI with, along with the required region.

You must ensure that:

  • Your AMI does not have an Encrypted volume
  • Your AMI storage volumes are less than 150 GB in total
  • Your AMI is in the correct region

To share your AMI:

  1. Navigate to your AMI within the AWS console. 

  2. On the Permissions tab, under Shared account ID, click Add account ID.

  3. Specify the AWS account ID displayed in the machine configuration panel on Lab Builder, and then click Share AMI.

Your account is now added to the shared accounts for that AMI. You can enter the AMI ID in Lab Builder and it's ready to use.

Lab Builder runs verification checks when you enter an AMI ID. It checks whether it has access to the AMI and whether the images are under the 150 GB maximum. If there's a problem, Lab Builder displays an error.

If you get an error, ensure:

  • Your AMI does not have an Encrypted volume.
  • Your AMI storage volumes are less than 150GB in total.
  • Your AMI is in the correct region.
  • Your AMI is correctly shared with the right account.

For a step-by-step guide on configuring your first machine in AWS and importing it into Lab Builder, please see our The Human Connection blog:

  1. Building Your First Practical Lab (Part 1)
  2. Building Your First Practical Lab (Part 2)