Use an image in a lab

An image becomes useful when a lab boots from it. That happens on the vm resource’s image block, which takes the image’s reference as its name.

References

Kind	Reference	Example
An image your team built	team-slug/image-name	acme/dev-tools
An Instruqt base image	The bare name	ubuntu, k3s

Either can carry a version tag, separated by a colon: acme/dev-tools:v2, ubuntu:24.04.

Base images are maintained by Instruqt rather than owned by your team, which is why they have no team-slug/ prefix. Write them as the catalog lists them — ubuntu, debian, rockylinux — optionally with one of their published tags.

In HCL

resource "vm" "workstation" {
  image {
    name = "acme/dev-tools:v2"
  }

  resources {
    cpu    = 2
    memory = 2048
  }
}

The image block is required, and name is the only required field in it. username and password are for pulling from a private third-party registry, and are not needed for an Instruqt image.

Booting a base image directly and doing the light work at startup is a perfectly good option when the setup is small:

resource "vm" "workstation" {
  image {
    name = "ubuntu:24.04"
  }

  resources {
    cpu    = 2
    memory = 4096
  }

  startup_script = <<-EOF
    #!/bin/bash
    apt-get update && apt-get install -y nginx
  EOF
}

The two combine well: build an image for the heavy, slow, shared part, and use a startup_script for the per-lab tweaks.

Caution

This is a virtual machine image, not a container image. A vm resource will not boot a container image from Docker Hub — those belong on a container resource.

In the UI

1. Open the lab’s Sandbox and select the virtual machine, or add one.
2. Expand the Image section.
3. Select Add a new public or private image.
4. In Custom image, enter the reference — for example acme/dev-tools:v2.

Use a preset is the other option: a short list of Instruqt’s base images, which also sets a sensible CPU and memory for the one you pick. Your team’s own images are reached through the custom field.

How a reference resolves

Reference	Resolves to
With a tag — acme/dev-tools:v2	The live digest under that tag: its newest published artifact.
Without a tag — acme/dev-tools	The highest version number the image has published.

An untagged reference is resolved by version number, not by publish date. v10 beats v9, and a tag that is not a version number — stable, edge — is never picked. An image whose tags are all words cannot be referenced without a tag at all.

Resolution happens when a session starts, so a lab picks up a newer version without being edited.

Tip

Pin a version in labs you have shipped. acme/dev-tools:v2 keeps giving every learner the same machine; acme/dev-tools changes under you the next time somebody publishes.

Before you change an image

An image’s Used by tab lists the labs that boot from it. Check it before publishing a new version over an image or deleting one — those are the labs a change reaches.

Publishing a new version is safe for labs that pin an older one; it reaches the labs that follow the newest. Deleting is not safe either way: see Manage images and versions.

Visibility

A Private image can only be referenced by labs in the team that owns it. A Public image — which includes every Instruqt base image — can be referenced by any team.