Build an image

Building an image means booting a VM from an image you already have, changing it, and publishing what you end up with. This page walks through one build from start to finish.

Start a build session

1. In the sidebar, click Building blocks → Images.
2. Click Create image.
3. In Base image, pick what to build on top of. The list is split into System images — Instruqt’s base images — and Team, your own published images. The field is searchable.
4. In Version, pick which snapshot of that base to boot. Latest is the default and follows whatever the base publishes; a specific version always boots the same filesystem.
5. Click Start building.

The image’s name and description are not asked for here. Every build starts from an existing image, and what you are building only gets named when you publish it.

To build on top of one of your own published images, you can skip straight to step 4: click New version on the image’s row menu, or on its detail page. The base is already chosen.

The platform then provisions a VM for you. It moves through Starting while the machine boots and the agent connects, and the builder opens once it is running. This usually takes a minute or two.

The builder

The work area has two panels:

• Terminal — a full shell on the VM. Install packages, start services, run scripts, pull down whatever the image needs.
• Editor — a file browser and editor for the VM’s filesystem, for writing config files and dropping files in by hand.

They open stacked as tabs with the terminal in front. Drag a tab to split them into columns or rows; the arrangement is remembered for your next build. The pair is fixed — you cannot close either panel or add a third.

Everything you do here is happening on a real machine. A package you install is installed, a service you enable is enabled, and all of it is what gets captured when you publish.

An example

# Refresh the package lists and install what the lab needs
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv

# Pre-install the libraries, so lab startup doesn't have to
pip3 install numpy pandas matplotlib jupyter

# Drop the package cache — it only makes the published image bigger
sudo apt-get clean
sudo rm -rf /var/lib/apt/lists/*

The last two lines matter more than they look. Anything left on disk is published with the image, and a smaller image boots faster in every lab that uses it.

Checkpoints

A checkpoint is a snapshot of the build VM as it is right now — its filesystem, its installed packages, its running state. Take one before something risky and you can put the machine back.

Checkpoints belong to the session, not to the image. They are not published versions, and they are destroyed with the VM when the session ends.

Click Checkpoints in the builder header to open the rail.

Action	What it does
Create	Snapshots the running VM. You describe what you just changed — that description is the only thing you will have to recognise it by later.
Roll back	Puts the VM back to that checkpoint and reconnects the terminal to the restored machine. Everything changed since is discarded and cannot be recovered.
Delete	Removes a checkpoint from the session’s history. The VM keeps the state it is in — you just lose the ability to roll back to that point.

The rail always holds one checkpoint you did not take: Initial state, the machine as it booted. Rolling back to it resets the build to the pristine base image without ending the session, and it cannot be deleted.

Tip

Take a checkpoint before a large install or a system-wide configuration change. Rolling back is near instant; starting the session over is not.

Keep the session alive

A build session runs for two hours from the moment the VM is editable, and is reclaimed after 15 minutes with no activity.

The builder sends a heartbeat while its tab is open, so a session you are working in stays alive on its own. If you leave it idle, a warning appears a few minutes before the session ends, and you can carry on from there.

Neither clock can be extended from the builder. Publish while you still have time — an expired session is destroyed along with every checkpoint in it.

Publish

1. Click Publish in the builder header.
2. If the session was built on one of your team’s own images, choose under Publish as whether this is a new version of that image or a new image. Building on an Instruqt base image, or on a protected image, only offers a new image — see Base images.
3. For a new image, enter the Image name. Up to 100 characters, and it has to be free within your team. This becomes team-slug/name, and it cannot be changed later.
4. Enter the Version tag. The field is prefilled by counting up from the image’s newest numeric tag, or v1 if there is nothing to count from.
5. Optionally add a Description — what changed in this version. Up to 500 characters, shown beside the version in the catalog.
6. Click Publish.

Version tag rules

Rule	Detail
Registry tag syntax	Starts with a letter, number or underscore, then letters, numbers, dots, dashes and underscores. Up to 128 characters.
New for this image	A tag the image already has is refused. Publish a new number instead.
latest is reserved	Kept for Instruqt’s managed base images. Give your version a number.
Use a number you can sort	An untagged reference in a lab resolves to the highest version number, so v1, v2, 1.4.2 all work and a word like stable is never picked. See How a reference resolves.

What happens next

Publishing flattens the running VM and pushes it to the registry. That takes minutes rather than seconds, so the dialog does not hold you there: it hands you back to the images list, where a Publishing row in Drafts tracks the push and turns into a catalog entry when it lands — or into a failed row carrying the reason.

The VM is torn down with the publish. To make further changes, start a new session with New version.

Each publish adds a version; the ones already published are untouched. That history is what lets a lab pin an old version and keep working.

Discard

If the build is not worth keeping, click Discard & Exit.

This stops the VM and permanently deletes it, along with every file you changed, every package you installed and every checkpoint from the session. Versions you already published are unaffected. It cannot be undone.

Nothing is written to the catalog, and you can start a new session whenever you like.