Task

Defined intasks.hcl

The task resource defines interactive activities that users must complete during a lab. Tasks can include multiple conditions with validation scripts, setup procedures, and solution scripts. Tasks are embedded in instruction pages and provide automated checking of user progress.

Use Cases

As a lab author, you use tasks to create hands-on learning experiences with automated validation:

Skill Validation: Create practical exercises that verify users can perform specific technical tasks correctly
Progressive Learning: Build sequences of tasks that gradually increase in complexity to scaffold learning
Granular Feedback: Break complex tasks into smaller conditions with individual lifecycle scripts for clearer guidance

Tasks transform passive instruction into active learning experiences where users practice real-world skills with immediate validation and guidance.

HCL Syntax

Basic Syntax

1
resource "task" "create_file" {
2
  description = "Create a file in the home directory"
3

4
  config {
5
    target = resource.container.ubuntu
6
  }
7

8
  condition "create_file" {
9
    description = "Create /tmp/hello.txt"
10

11
    check {
12
      script = "scripts/task/create_file/check_file.sh"
13
    }
14
  }
15
}

Full Syntax

1
resource "task" "docker_setup" {
2
  description      = "Complete the Docker setup"
3
  success_message  = "Excellent! You've completed all requirements."
4

5
  config {
6
    target               = resource.container.ubuntu
7
    user                 = "root"
8
    group                = "root"
9
    working_directory    = "/home/user"
10
    timeout              = "30s"
11
    environment = {
12
      PATH = "/usr/local/bin:/usr/bin:/bin"
13
    }
14
    success_exit_codes   = [0]
15
    failure_exit_codes   = [1, 2]
16

17
    parallel_exec {
18
      condition = true
19
      check     = false
20
      solve     = false
21
      setup     = false
22
      cleanup   = false
23
    }
24
  }
25

26
  condition "setup_environment" {
27
    description = "Set up the Docker environment"
28

29
    config {
30
      timeout = "60s"
31
    }
32

33
    setup {
34
      script = "scripts/task/docker_setup/setup_docker.sh"
35
    }
36

37
    check {
38
      script          = "scripts/task/docker_setup/check_docker.sh"
39
      failure_message = "Docker is not running correctly"
40
    }
41

42
    solve {
43
      script = "scripts/task/docker_setup/solve_docker.sh"
44
    }
45

46
    cleanup {
47
      script = "scripts/task/docker_setup/cleanup_docker.sh"
48
    }
49
  }
50

51
  condition "create_container" {
52
    description = "Create and run a container"
53

54
    check {
55
      script = "scripts/task/docker_setup/check_container.sh"
56

57
      config {
58
        timeout = "45s"
59
      }
60
    }
61

62
    solve {
63
      script = "scripts/task/docker_setup/solve_container.sh"
64
    }
65
  }
66
}

Resource Structure

1
task
2
├─ description (required)
3
├─ success_message (optional metadata)
4
├─ config (default configuration for all scripts)
5
│  ├─ target, user, group, working_directory
6
│  ├─ timeout, environment
7
│  ├─ success_exit_codes, failure_exit_codes
8
│  └─ parallel_exec
9
│     └─ condition, check, solve, setup, cleanup
10
└─ conditions[] (one or more required)
11
   ├─ id (label), description (required)
12
   ├─ config (inherits from task config, can override)
13
   └─ script blocks (multiple of each type allowed)
14
      ├─ setup[] (runs when condition starts)
15
      ├─ check[] (runs during validation)
16
      ├─ solve[] (runs when skipped)
17
      └─ cleanup[] (runs when condition completes)
18
         └─ each script: script path, failure_message, config override

Fields

Field	Type	Required	Description
`description`	string	✓	Add a short explanation of what users are expected to achieve.
`prerequisites`	list(reference)`chapter`, task, quiz	—	Tasks that must complete before this task can start
`success_message`	string	—	A message shown to learners when they complete the task correctly. Use it to confirm success or provide a next step.
`config`	block	—	Default execution context for all conditions
`condition`	block	—	Validation conditions that must all pass for task completionrepeatable

Configuration

Default execution context for all conditions

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Condition

Validation conditions that must all pass for task completion

Field	Type	Required	Description
`id`	label	✓	An internal identifier for the condition. Used to reference this condition within the task configuration. Not visible to learners.
`description`	string	✓	Explain what this condition checks or validates for the learner. Keep it short and action-oriented so users understand what success means.
`config`	block	—	Use this to override task-level settings for this specific condition. Common overrides include timeout, working directory, or user permissions.
`check`	block	—	Validation scripts to verify task completion (required)repeatable
`solve`	block	—	Scripts to automatically solve this conditionrepeatable
`setup`	block	—	Scripts to run before checks startrepeatable
`cleanup`	block	—	Scripts to run after task completes (success or failure)repeatable

Configuration

Execution context override for this condition

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Check

Validation scripts to verify task completion (required)

Field	Type	Required	Description
`script`	string	—	The file location of the script to execute ConstraintsMust be a script file (.sh, .bash, .py, .rb, .js)
`failure_message`	string	—	The message to show if the check has failed
`config`	block	—	Execution context override for this script

Configuration

Execution context override for this script

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Solve

Scripts to automatically solve this condition

Field	Type	Required	Description
`script`	string	—	The file location of the script to execute ConstraintsMust be a script file (.sh, .bash, .py, .rb, .js)
`failure_message`	string	—	The message to show if the check has failed
`config`	block	—	Execution context override for this script

Configuration

Execution context override for this script

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Setup

Scripts to run before checks start

Field	Type	Required	Description
`script`	string	—	The file location of the script to execute ConstraintsMust be a script file (.sh, .bash, .py, .rb, .js)
`failure_message`	string	—	The message to show if the check has failed
`config`	block	—	Execution context override for this script

Configuration

Execution context override for this script

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Cleanup

Scripts to run after task completes (success or failure)

Field	Type	Required	Description
`script`	string	—	The file location of the script to execute ConstraintsMust be a script file (.sh, .bash, .py, .rb, .js)
`failure_message`	string	—	The message to show if the check has failed
`config`	block	—	Execution context override for this script

Configuration

Execution context override for this script

Field	Type	Required	Description
`target`	referencecontainer, vm	—	Select the sandbox component where this task will run. The task executes commands inside the chosen environment.
`user`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`group`	string	—	Set the user or group identity under which the task runs inside the container. This helps control permissions.
`working_directory`	string	—	Specify the directory path where the task commands will execute. Leave empty to use the default working directory.
`environment`	map(string)	—	Environment variables for script execution
`timeout`	string	—	Set how long the task can run before it stops automatically. Use this to prevent tasks from hanging indefinitely. ConstraintsMust be a valid duration (e.g. 30s, 5m)
`success_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`failure_exit_codes`	list(number)	—	Define success and failure exit codes. Exit code 0 means success, while any other value typically indicates failure.
`parallel_exec`	block	—	Configure parallel execution for lifecycle scripts

Parallel Exec

Configure parallel execution for lifecycle scripts

Field	Type	Required	Description
`condition`	bool	—	Execute all condition blocks in parallel Default`false`
`check`	bool	—	Execute all check scripts in parallel within a condition Default`false`
`solve`	bool	—	Execute all solve scripts in parallel within a condition Default`false`
`setup`	bool	—	Execute all setup scripts in parallel within a condition Default`false`
`cleanup`	bool	—	Execute all cleanup scripts in parallel within a condition Default`false`

Default Configuration

The following defaults are applied automatically:

1
config {
2
  timeout              = "30s"
3
  working_directory    = "/"
4
  environment          = {}
5
  user                 = "root"
6
  group                = "root"
7
  success_exit_codes   = [0]
8
  failure_exit_codes   = []
9

10
  parallel_exec {
11
    condition = false
12
    check     = false
13
    solve     = false
14
    setup     = false
15
    cleanup   = false
16
  }
17
}

Examples

Simple File Creation Task

1
resource "task" "create_file" {
2
  description = "Create a configuration file"
3

4
  config {
5
    target = resource.container.ubuntu
6
  }
7

8
  condition "file_exists" {
9
    description = "Create /etc/myapp.conf"
10

11
    check {
12
      script = "scripts/task/create_file/check_config_file.sh"
13
    }
14

15
    solve {
16
      script = "scripts/task/create_file/create_config_file.sh"
17
    }
18
  }
19
}

Multi-Condition Docker Task

1
resource "task" "docker_setup" {
2
  description     = "Set up Docker environment"
3
  success_message = "Great! Docker is now configured and running."
4

5
  config {
6
    target = resource.container.ubuntu
7
    timeout = "60s"
8
  }
9

10
  condition "install_docker" {
11
    description = "Install Docker"
12

13
    setup {
14
      script = "scripts/task/docker_setup/install_docker.sh"
15
    }
16

17
    check {
18
      script          = "scripts/task/docker_setup/check_docker_installed.sh"
19
      failure_message = "Docker installation failed. Check the logs."
20
    }
21

22
    solve {
23
      script = "scripts/task/docker_setup/solve_install_docker.sh"
24
    }
25
  }
26

27
  condition "start_service" {
28
    description = "Start Docker service"
29

30
    check {
31
      script = "scripts/task/docker_setup/check_docker_running.sh"
32
    }
33

34
    solve {
35
      script = "scripts/task/docker_setup/start_docker.sh"
36
    }
37
  }
38

39
  condition "run_container" {
40
    description = "Run a test container"
41

42
    check {
43
      script = "scripts/task/docker_setup/check_test_container.sh"
44

45
      config {
46
        timeout = "45s"
47
      }
48
    }
49

50
    solve {
51
      script = "scripts/task/docker_setup/run_test_container.sh"
52
    }
53

54
    cleanup {
55
      script = "scripts/task/docker_setup/cleanup_test_container.sh"
56
    }
57
  }
58
}

Task with Custom Configuration

1
resource "task" "advanced_networking" {
2
  description = "Configure advanced network settings"
3

4
  config {
5
    target = resource.container.network_lab
6
    user   = "student"
7

8
    environment = {
9
      NETWORK_CONFIG = "/etc/networks.conf"
10
      DEBUG_MODE     = "true"
11
    }
12
  }
13

14
  condition "configure_bridge" {
15
    description = "Set up bridge network interface"
16

17
    check {
18
      script = "scripts/task/advanced_networking/check_bridge.sh"
19
    }
20
  }
21
}

Parallel Execution Task

1
resource "task" "parallel_checks" {
2
  description = "Run multiple parallel validations"
3

4
  config {
5
    target = resource.container.test_env
6

7
    parallel_exec {
8
      check = true  # Run all check scripts in parallel
9
    }
10
  }
11

12
  condition "check_service_a" {
13
    description = "Validate service A is running"
14

15
    check {
16
      script = "scripts/task/parallel_checks/check_service_a.sh"
17
    }
18
  }
19

20
  condition "check_service_b" {
21
    description = "Validate service B is running"
22

23
    check {
24
      script = "scripts/task/parallel_checks/check_service_b.sh"
25
    }
26
  }
27

28
  condition "check_service_c" {
29
    description = "Validate service C is running"
30

31
    check {
32
      script = "scripts/task/parallel_checks/check_service_c.sh"
33
    }
34
  }
35
}

Script Execution Flow

Tasks execute scripts in a specific order:

Setup scripts: Run when a condition becomes active
Check scripts: Run when validating the condition
Solve scripts: Run when the user skips the condition
Cleanup scripts: Run when the condition completes (success or skip)

Within each condition:

All setup scripts execute first (in order)
Check scripts execute during validation
Solve scripts execute only when skipped
Cleanup scripts execute last (in order)

Usage in Instructions

Tasks must be referenced in instruction markdown using the <instruqt-task> component:

1
## Complete the Setup
2

3
<instruqt-task id="docker_setup"></instruqt-task>
4

5
Continue to the next step once the task is complete.

Best Practices

Clear Descriptions: Write descriptive names for tasks and conditions that explain what users need to do
Granular Conditions: Break complex tasks into smaller, logical conditions for better user feedback
Error Messages: Provide helpful failure messages in check scripts
Timeouts: Set appropriate timeouts based on expected script execution time
Cleanup: Always clean up resources in cleanup scripts to avoid side effects
Script Organization: Organize scripts into subdirectories matching the task resource name for easier readability (e.g., scripts/task/docker_setup/check_docker.sh). If you need to share a script across multiple tasks, you can customize the directory structure as needed — the convention is a starting point, not a strict requirement.
Configuration Inheritance: Use task-level config for common settings, override at condition/script level when needed