Image builder
Image builder is your team’s catalog of the images a lab’s virtual machines boot from, and the place you build your own. You start a build session on top of an existing image, configure the running machine through a terminal and a file editor in the browser, and publish what you end up with as a new version.
There is no Packer file, no build pipeline and nothing to run locally. The machine you are configuring is the machine that gets published.
When to build an image
Section titled “When to build an image”- Move slow work out of lab startup. A package install that takes three minutes at boot takes it once, at build time, instead of once per session.
- Share one environment across labs. A single image every lab in the team boots from, so a fix lands in one place.
- Configure what a script cannot. Interactive installers, desktop applications, services that have to be set up in a particular order.
If all you need is a config file or one extra package, a VM startup_script is simpler than building an image. Build an image when the setup is slow, shared, or awkward to script.
Images, versions and digests
Section titled “Images, versions and digests”An image is a catalog entry owned by one team. Its reference is team-slug/image-name — for example acme/dev-tools — and that is the string a lab writes. The name is fixed once the image exists, because labs pin it.
A version is a tag on that image: v1, v2, 2.4.1. A lab can pin one, or leave the tag off and let the platform resolve it.
A digest is the actual published artifact under a tag. Each version card in the UI lists its digests newest first, and the newest published one is marked Live — that is what the tag resolves to now.
Each published version is a disk overlay chained onto the image it was built from. Booting a lab walks that chain back to the base, which is why publishing a small change produces a small artifact rather than a whole new disk.
Base images
Section titled “Base images”Instruqt maintains a set of public base images that every team can build on and boot from. They belong to the instruqt team, they are protected, and you refer to them by their bare name.
| Image | Versions | Contains |
|---|---|---|
ubuntu | 22.04, 24.04, latest | Ubuntu LTS |
debian | 11, 12, latest | Debian stable |
fedora | 42, 43, 44, latest | Fedora |
centos | 8, latest | CentOS 8 (legacy) |
rockylinux | 8, 9, latest | Rocky Linux |
docker | latest | Docker Engine, preinstalled |
k3s | latest | K3s (lightweight Kubernetes), preinstalled |
You cannot publish a new version onto a base image — the catalog is not a team’s to write to. Building on one and publishing saves the result as a new image of your own. The same applies to any team image that is protected.
Build sessions
Section titled “Build sessions”A build session is a real VM, running for you, with a terminal and a file editor attached. Sessions are private: you only ever see your own, and nobody else can open one of yours.
A session ends in one of four ways:
| Ending | What happens |
|---|---|
| Published | The VM is flattened, pushed to the registry as a version, and torn down. |
| Discarded | You chose to throw it away. The VM and everything on it is destroyed. |
| Expired | The session hit its two-hour time limit. |
| Failed | The session could not start, or a lifecycle step failed. The error is on the draft row. |
In every case the VM is gone. Only a publish leaves anything behind.
Session limits
Section titled “Session limits”| Limit | Value | What it means |
|---|---|---|
| Time limit | 2 hours | Counted from the moment the VM is up and editable. The session is reclaimed when it runs out. |
| Idle timeout | 15 minutes | A session nobody is working on is torn down. The builder sends a heartbeat while its tab is open, and warns you before it ends. |
Statuses
Section titled “Statuses”An image in the catalog carries one of these:
| Status | Meaning |
|---|---|
| Importing | A disk is being ingested. See Import an image. |
| Draft | A build session exists, but nothing has been published from it yet. |
| Publishing | A version is being pushed to the registry. |
| Published | At least one version is available. Labs can boot from it. |
| Failed | The last import or publish did not finish. |
Visibility
Section titled “Visibility”An image is Private — only your team can see it and boot labs from it — or Public, meaning every team on Instruqt can. Images you build are private; Instruqt’s base images are public.
How this section is organised
Section titled “How this section is organised”| Page | Covers |
|---|---|
| Build an image | Starting a session, the terminal and editor, checkpoints, publishing, discarding. |
| Import an image | Bringing in a GCP Compute Engine image or a disk file you already have. |
| Manage images and versions | The readme, protection, deleting an image or a single digest, drafts. |
| Use an image in a lab | Referencing an image from a vm resource, and how a reference resolves. |