Coming from Tracks

If you already author Tracks, use this guide to find familiar features in the Lab editor. Labs separate instructions, activities, sandbox resources, and tabs; not every Track setting has a direct equivalent. For the new vocabulary and the features removed in 2.0, see What’s New in 2.0.

Quick reference

In Tracks	In Labs
Challenge	A Page, with a Task when the challenge had a check. See Chapter or Page?
Challenge notes	No loading page. Move the content to the first page. See Challenge notes
VM shell	Shell on the Terminal tab. See VM shell
Custom VM image	Not reusable. Start from an Instruqt-managed image. See VM images
Allow external ingress	No equivalent setting. See External ingress
Track setup script	Exec resource or the VM’s Startup Script. See Map your Track script layout
Track cleanup script	No equivalent. See Cleanup scripts
Challenge setup, check, solve, and cleanup scripts	Scripts on a Task → Condition. See Task scripts
Track feedback	Feedback blocks on pages. See Track feedback
Custom loading messages	Not available. See Custom messages

Challenge notes

In Tracks, challenge Notes are introduction content shown while the track loads. Labs load all resources at the start and have no notes page to read while users wait. See Not in 2.0.

Move introduction content to the first Instructions page. For reference content users should keep open while they work, add a Note tab: open Tabs → Add Tab → Note, add the content as markdown, and add the tab to a panel in Layouts.

See Note tabs and designing layouts.

Chapter or Page?

A Track challenge usually becomes one Page, with a Task on it when the challenge had a check script. A Chapter groups related pages and has no Track equivalent; use one when you want to group pages by topic. Create both from the + menu in Instructions.

See chapters and pages.

VM shell

Configure the interactive shell on the Terminal tab, not on the VM. Open Tabs → Add Tab → Terminal, select the VM as Target, and set Shell to the shell you need, such as /bin/bash. That shell must exist inside the VM. Add the terminal tab to your layout.

See Terminal tabs.

VM images

Custom Track VM images, e.g. instruqt/docker-28-3, are Google Cloud Compute images and cannot be reused in Labs. Cloud image names such as ubuntu-os-cloud/ubuntu-2404-lts-amd64 do not work either. A Lab VM’s Image is an OCI image reference.

Start from an Instruqt-managed image and recreate your Track image customizations in the VM’s Startup Script. See VM images.

External ingress

The Track setting Allow external ingress for HTTP, HTTPS and High Ports has no equivalent setting in the Lab editor.

For a web application users access inside the lab, add a Service tab and configure its Target, Port, and Scheme. This proxies HTTP/HTTPS traffic to that application; it does not open ports to clients outside the lab. See Service tabs.

If your Track depends on clients connecting from outside the lab, contact Instruqt Support before migrating it.

The ingress resource is unrelated to this setting: it routes traffic to services running in Kubernetes or Nomad clusters.

Cleanup scripts

The VM’s Startup Script does not have a paired VM cleanup-script field. A task condition has a Cleanup script phase under Activities, but that belongs to the task lifecycle. Do not use it as a guaranteed hook for when the user stops the lab or the sandbox is destroyed.

See VM configuration and task script phases.

Track feedback

Tracks collect feedback through two settings: After user completes all challenges, which is on by default, and During any challenge. Labs have no lab-level feedback setting. Feedback is a block you place in the content, and a lab collects no feedback until you add one.

To ask for feedback at the end, add a Feedback block to the final page.
To ask for feedback during the lab, add a Feedback block to each page where you want to ask.

In the Visual editor, type / on an empty line and choose Feedback, or use Insert → Blocks → Feedback. Users can rate the content and leave feedback there.

Feedback does not replace the Completion block that lets users finish the lab. See the content editor and lab completion.

Custom messages

In Tracks, Custom messages are the loading messages shown while a track starts. Labs do not carry forward default or custom loading messages. See Not in 2.0.

For messages shown when users check their work, open the task in Activities:

Set Success Message for the message shown when all conditions pass.
Set Failure Message on a Check script to explain what users need to fix.

Put general guidance in the page instructions or a Note tab. See task details and script configuration.

Task scripts

Start with one task and one condition:

Open Activities → Create new activity → Task. Enter a name and description, then select the sandbox Target where scripts run.
Choose Add condition, describe what it checks, and add a Check script. Add Setup, Solve, or Cleanup scripts only when that condition needs them.
Save the task, open an Instructions page, and insert the task using the Visual editor’s task menu. Creating a task alone does not put it on a page.

To decide which Track scripts become task scripts and which become sandbox resources, see Map your Track script layout. See creating tasks for the full workflow and script lifecycle.

Map your Track script layout

The Track editor groups scripts under Track, per host (e.g. workstation), and under Challenges, per challenge. Labs group them by responsibility instead: Sandbox prepares the environment; Activities → Task → Condition validates the user’s work. Classify each script by what it does, not just its filename or old folder.

Track script or purpose	Where it belongs in a Lab
Track-level setup for a host, e.g. `workstation`	Sandbox → Exec for custom container setup, targeting the corresponding container. For VM boot-time setup, use that VM’s Startup Script instead. Move readiness checks, files, and dependencies to native Lab resources, and remove waits for the Track bootstrap marker.
Challenge setup that prepares a particular exercise	Task → Condition → Setup. When the task becomes active, the setup scripts of all its conditions run, not one condition at a time. Keep sandbox-wide provisioning out of it.
Challenge check that validates the user’s work	Task → Condition → Check. Installing packages or starting a database is setup, not validation.
Challenge solve that supplies the solution	Task → Condition → Solve, which runs when the condition is skipped.
Challenge cleanup after the exercise	Task → Condition → Cleanup, which runs when the condition completes or is skipped.
Track-level teardown when the sandbox stops	No direct equivalent in the task script slots. A condition’s Cleanup is not a sandbox-stop hook; see Cleanup scripts.

Set the task’s Target to the container or VM where its scripts should run; use a condition’s Configuration Override if it needs a different target. Do not assume a script still runs on the host implied by its old Track folder name.

One condition, four script types

A condition represents one requirement, not one script phase. For an exercise named configure_database, start with one Task and one Condition such as database_configured. Put its preparation script in Setup, validation in Check, solution in Solve, and exercise cleanup in Cleanup, all inside that same condition. Add only the script types it needs.

Add another condition when there is another requirement to validate, not to hold the next script phase. Multiple scripts of the same type can also belong to one condition. See the Task resource structure.

Connect the environment, task, and page

Use this order for a first port; it is a migration checklist, not an enforced editor order:

Create the Sandbox resources and move environment preparation there. Configure targets, dependencies, and health checks before adding exercise scripts.
Create the exercise’s Instructions → Page. In Activities, create its Task and Condition, map the scripts using the table above, then insert the Task into that page. A Task listed in Activities alone is not visible to the user.
Create the required Tabs, such as a Terminal targeting workstation. Add Instructions and those tabs to the page’s Layout, or its inherited default layout.
Test a fresh lab session. Confirm the page and Task are visible, the target environment is ready, and Check fails before the required work and passes afterwards. Test Solve and Cleanup too if you added them.