Instruqt Decision Trees

Container, virtual machine, or sandbox preset

The first architectural decision in any track. Boot time, capability, image selection, and which lifecycle helpers work all flow from this single choice. Walk the questions in order. Tree 11 covers the preset-versus-custom choice in more depth — start there if your product already has a preset.

Choosing the right tab type

Most production tracks pair the terminal with one or more browser-rendered surfaces. The tab type is how you choose what the learner sees — and the choice depends entirely on what the surface connects to.

One host, many containers, many VMs, or hybrid

Most tracks need exactly one host. Some need two or more — a workstation plus the system being managed, a workstation plus a database, a primary plus a replica. The shape of the composition determines the recipe. Take the compute decision from Tree 1 first, then walk this tree.

Choosing the right cloud account block

If the lesson touches a cloud, the cloud account block in config.yml is what makes the credentials show up in the workstation. The wrong block — or a block configured by copy-paste from a different cloud — produces silent auth failures that look like permission bugs. A common trap: scripts that reference INSTRUQT_AWS_*, INSTRUQT_AZURE_*, or INSTRUQT_GCP_* variables receive empty strings at runtime when no matching resource block is declared.

Passing values between hosts and across challenges

A single-host track has one shell, one filesystem, and one process tree — state lives wherever you put it. The moment a track has two hosts, or one host plus multiple challenges, you need a discipline for moving values across those boundaries. The three options — agent variable, JSON broker, and cross-VM env passthrough — are not mutually exclusive; complex multi-VM tracks routinely use all three for different purposes.

Lazy, granular, or scored

A check script is the conversation the lab has with the learner when they click Check. The shape of that conversation is a design choice. The wrong shape teaches the wrong thing — a single-line "Try again" on a check that tested nine things is a worse experience than no check at all. Tree 13 (engagement validation depth) covers when to add anti-cheat instrumentation on top of any of these.

Step-based, prose, recap, or read-only intro

Every challenge has a body — the markdown the learner reads in the assignment pane. The body's shape signals what kind of work is ahead: study this, do these steps, recall what we covered, complete this single task. Picking the wrong shape works against the lesson.

Heredoc, sparse-checkout, or full git clone

Most tracks need to put a project tree in front of the learner at the start of a challenge: a config file to edit, a function to implement, a folder of fixtures. There are three reasonable ways to do that, and the choice depends on size, sensitivity of source, and how much editorial control you want. Tree 14 covers the related image-vs-runtime decision when the dependency stack itself is heavy.

How custom should the lesson feel

Branding is a spectrum, not a switch. At one end: a stock root prompt and a generic shell. At the other: a non-root user with a customer-themed prompt, a custom CLI wrapper, a branded portal page, and loading messages that name the product. The right point on the spectrum is set by what the lesson is teaching.

timelimit, idle_timeout, pausable, skipping_enabled

A track has a clock whether you set one or not. Choosing the clock settings deliberately matters because the wrong settings sabotage the experience: a workshop that times out mid-lesson, a self-paced lab that demands an unbroken hour, an instructor who cannot skip a challenge that ran long.

When the preset is enough and when it is a wall

A sandbox preset gives you a shared, fast-starting environment that the platform manages for you. The trade is loss of control: you can't run setup scripts in track_scripts, can't bring a custom image, can't compose multiple hosts, can't inject secrets, can't shape per-track networking. The preset is a real win when its defaults already match the lesson; it is a wall the moment they don't. New contributors often pick presets thinking they're "easier" and then hit that wall when a setup script becomes necessary — start with config.yml if there is any doubt.

secrets block, environment block, runtime fetch, or never

Anything sensitive — an API key, an SSH private key, a registry credential, a license key, a long-lived service token — needs a deliberate home. Two anti-patterns dominate: baking the value into config.yml's environment block (visible to every learner via the debug log, and committed to git history forever) and base64-encoding it inside a setup script (base64 is not encryption). The right home depends on what the value is and how it gets used. The general framing: anything that proves identity or grants access goes in the secrets block; anything that just shapes behavior can sit in environment.

When to add anti-cheat instrumentation, and how much

Engagement validation is the toolbox of patterns that confirm a learner actually did the lesson rather than clicked Check ten times in a row: shell-history forensics, anti-rapid-clicking attempt counters, marker files, cron-based pause trackers, query-counter snapshots. The patterns are powerful but heavy. Use them where the publisher needs to detect cheating or attribute progress to specific challenges. Avoid them where they will frustrate genuine learners who legitimately skip ahead or click through quickly.

Bake into a published image, or build at setup time

Either you publish a custom image with the dependencies pre-installed, or you build the environment at setup time using heredocs and install commands. Both are legitimate. The trade-off shapes most architecture choices for a track. Custom image: fast learner experience, slow author iteration (Packer rebuild loop). Heredoc and install scripts: self-contained track, longer learner cold starts. Pick deliberately. This tree pairs with Tree 8 (project files) — they answer related but distinct questions.

Picking the validation shape for a question or short-answer challenge

Three valid shapes for "did the learner get the right answer." The native quiz challenge type is easiest but only covers multiple-choice. The file-based pattern (learner echoes an answer to a known path) is a strict generalization — any short-answer question, custom validation logic, targeted fail-message feedback. A full programmatic check (Mocha/Chai for JS, pytest, plain bash) is for cases where the answer is the state of a system, not a string. Pick the simplest shape the lesson supports.

AssignmentLeft vs AssignmentRight, and how wide the assignment pane should be

The default_layout and default_layout_sidebar_size fields under lab_config decide where the assignment lives and how much screen real estate it claims. The defaults work for most tracks; the wrong settings are surprisingly costly when the lesson does not match. AssignmentRight (tool area is the visual focus) is used by roughly 80% of tracks and is the right starting point if you are unsure. The sidebar size is a percentage of screen width — values around 30 give wide tools and a narrow assignment, values around 70 give a wide assignment and a narrow tool area. A challenge can override either via challenge-level lab_config (or precise multi-pane custom_layout) when one challenge in the track is structurally different from the rest.