Skip to content

You are viewing documentation for Instruqt 2.0 Labs which is in Beta currently. Official release date - 29 September, 2026. For Tracks documentation, please visit docs.instruqt.com.

Instruqt Lab Documentation

Creating Labs

An Instruqt lab is a directory of HCL configuration and markdown content that you develop locally and deploy through Git. This page walks the creation workflow end to end and shows the smallest valid lab configuration; each step links to a page that covers it in depth.

Labs can also be created and edited entirely in the platform UI — see the UI getting started guide. This page covers the code-first workflow.

The lab creation workflow

Section titled “The lab creation workflow”
  1. Initialize a project. instruqt lab init scaffolds a lab directory from an example. See Project setup.
  2. Configure the sandbox. Define the networks, containers, VMs, and other infrastructure resources your lab runs on. See Infrastructure setup.
  3. Add content and tasks. Write instructions in markdown, organize them into chapters and pages, and add tasks with validation scripts. See Content & tasks.
  4. Format and validate. instruqt lab format keeps the HCL consistent; instruqt lab validate checks the configuration locally. See Testing & Validation.
  5. Deploy. Connect the lab to a GitHub repository once; every git push then syncs to the platform automatically. See Integration with an External VCS and Testing & Deployment.
  6. Playtest and debug. Start the lab as a learner, and stream runtime logs when something misbehaves. See Testing & Deployment and Logs overview.

Initialize a project

Section titled “Initialize a project”
Terminal window
instruqt lab init

The command is fully interactive and walks you through four prompts: a lab title, a target directory, the example to start from, and a confirmation. The target directory defaults to the slug of your title — a lab titled “My Web Server Lab” lands in my-web-server-lab/.

You can start from six examples: Empty/skeleton lab, Container Terminal, Container Service, Kubernetes Terminal, Quizzes and questions, and Tasks and conditions. The skeleton is the minimal starting point; the others come with a working sandbox, quiz, or task setup to build on.

Terminal window
cd my-web-server-lab

For the full walkthrough — the generated file structure and setting up version control — follow Project setup.

A minimal lab

Section titled “A minimal lab”

The skeleton example is the smallest configuration that launches: a lab resource and the layout it references.

main.hcl
resource "lab" "main" {
  title       = "Skeleton Lab"
  description = "This is the Skeleton Lab.\nYou can use this as a minimal starting point for developing labs.\n\nFor more information, check ./assets/README.md"


  layout = resource.layout.single_panel
}
layouts.hcl
resource "layout" "single_panel" {
  column {
    instructions {
    }
  }
}

A lab resource requires three fields: title, description, and a layout reference. References use the resource.<type>.<name> syntax. File names are convention — the CLI parses every top-level .hcl file in the lab directory, so you are free to split resources across files (main.hcl, layouts.hcl, sandbox.hcl, and so on).

Instructional content attaches through a content block that organizes chapters and pages. Until the lab has one, instruqt lab validate reports a warning that the instructions panel will show no content — the lab is still valid. See Content & tasks for the full content structure.

Validate and iterate

Section titled “Validate and iterate”

Run these from the lab directory as you work:

Terminal window
instruqt lab format
instruqt lab validate

format rewrites the HCL for consistent layout; validate parses the configuration and checks resource rules without starting the lab. Both commands, their flags, and common failure modes are covered in Testing & Validation.

Deploy and test

Section titled “Deploy and test”

There is no publish command. Connect your lab to a GitHub repository once, and the platform syncs on every git push. Then start the lab as a learner to verify the experience end to end.

Section titled “Related”