Manage images and versions

Everything an image has after it is published — its history, its documentation, and the decisions that belong to it — lives on the image’s own page. Click a row in Building blocks → Images to open it.

The header carries the image’s name (with a copy button, since the name is what a lab writes), its visibility, when it was last updated, the Protected switch, New version, and a menu with Delete image. Below it are three tabs.

Overview

The Readme — long-form markdown describing what the image is, what is in it, and anything someone has to know before booting a lab from it.

This is the one piece of an image’s documentation you can edit after publishing, and it is what a teammate reads when deciding which image to use. Worth writing: what is installed and at what version, which ports are in use, any default credentials, and anything non-obvious about how the image expects to be used.

Click Edit to change it, or Add readme if there is none yet. You can write in the visual editor or in raw markdown — the two tabs edit the same text, so switching mid-edit keeps what you typed. Save commits it; Cancel throws the draft away.

Versions

One card per version tag, newest first, with the newest tag badged Latest. Each card shows when it was last pushed and by whom, the version’s description, and a table of its digests.

Column	What it shows
Digest	The artifact’s digest, with a copy button. The newest published one is badged Live — that is what the tag resolves to now.
Created	When it was published, and who published it.
OS/ARCH	The platform the image targets.
Size	The size of the published overlay — the change this version added, not the whole disk.

Used by

The labs that boot from this image. This is what is worth checking before you publish over an image or delete it, since those are the labs a change reaches.

Protection

The Protected switch on the image page stops the image, and every version under it, from being deleted. Turn it on for images live labs depend on.

While it is on, both Delete image and Delete this digest are disabled with the reason on hover. The protection has to come off first — the delete cannot override it.

Only team owners can change it. Everyone else sees whether the image is protected, without the switch, since the flag explains a disabled delete they can otherwise reach.

Protection also blocks publishing a new version onto the image: a build started from a protected image has to be published as a new image of its own.

What you cannot change

Field	Why
Name	The name is the reference (team-slug/name). Renaming would silently repoint every lab that uses it, so it is fixed at creation. To rename, publish under the new name and move labs across.
Version tag	A tag is what a lab pins. It is set at publish time and cannot be edited afterwards.
Visibility	Set when the image is created. Images you build are private to your team.

Delete a digest

Removes one published artifact, leaving the image and its other versions alone. Use it to clear out a broken or superseded publish.

1. Open the image and go to Versions.
2. On the digest’s row, click ••• → Delete this digest.
3. Confirm.

If it is the newest artifact on the image, the dialog says which version the labs that follow the newest one will fall back to — or that they will have none left. A digest that is still publishing cannot be deleted.

This cannot be undone.

Delete an image

Removes the image and all of its versions, from the catalog and from the registry.

1. Open the image, or find its row in the list.
2. Click ••• → Delete image.
3. If labs boot from this image, type the image’s name to confirm — the dialog names them, so you can see what breaks.
4. Click Delete image.

Labs that reference a deleted image stop starting. Check Used by first, and prefer deleting a single digest when that is all you meant.

This cannot be undone.

Drafts

Build sessions that have not become a catalog entry yet appear in Drafts, above the images table. Drafts are yours alone — you never see anyone else’s, and they never see yours.

Badge	State	Actions
Starting	The VM is being provisioned or is booting.	Discard
Editing	The VM is up and yours to work on.	Resume, Discard
Publishing	The version is being pushed. It resolves into a catalog entry on its own.	—
Discarding	The VM is being torn down.	—
Importing	A headless import, with its phase on the row.	—
Failed	The session or import did not finish. The error is on the row.	Dismiss

Resume reopens a live session in the builder. Discard tears its VM down. Dismiss clears a failed row — its VM is already gone, so there is nothing left to tear down.

A session that published, was discarded, or ran out of time leaves the list: the result is either in the catalog or nowhere.

Troubleshooting

Problem	What to do
The build ran out of time	A session lasts two hours. Start a new one and publish in stages — publish a working base as v1, then build the next layer on top of it.
The build was stopped after being idle	A session with no activity for 15 minutes is reclaimed. Keep the builder tab open while you work; it sends a heartbeat and warns you before the session ends.
Publish refused the version tag	The tag is already on this image, uses characters a registry tag cannot, or is latest, which is reserved. See Version tag rules.
Publish asked for a name	The session was built on an Instruqt base image or a protected image. Neither can take a new version — publish the result as a new image.
The import failed	Check the error on the draft row. Usually the GCP image reference is wrong or unreachable, it points at a family rather than an image, or the upload did not complete.
A lab cannot find the image	Confirm the image is Published and that the reference is team-slug/image-name. See Use an image in a lab.
Delete is greyed out	The image is protected. A team owner has to turn protection off first.