Runtime variables

This page describes how to define runtime variables and use them inside lifecycle scripts or challenge assignments.

Overview
Runtime variables allow you to use dynamic content in challenge assignments and lifecycle scripts. You can define runtime variables via our GraphQL API or Lifecycle Scripts.

These variables are configured per participant per host (e.g a user's VM or container instance) and can only be accessed from the given participant and host. 
It's not recommended to store secrets in runtime variables as the storage is not secure and everyone who has terminal access may be able to view them. 

Furthermore, cloud account related environment variables are automatically stored in the $INSTRUQT_ENV_VARS variable, and do not need to be redefined as runtime variables.
Runtime variables in Lifecycle Scripts
Register variables
In order to register a runtime variable in a host's lifecycle script, use the following command:
🐧 Linux Hosts
🪟 Windows Hosts
agent variable set {KEY} {VALUE}
For example, the following defines a runtime variable named COLOR with a value of RED. 
agent variable set COLOR RED
Agent-Variable-Set {KEY} {VALUE}
For example, the following defines a runtime variable named COLOR with a value of RED. 
Agent-Variable-Set COLOR RED
Runtime variable keys are case-insensitive.
Retrieve values
In order to retrieve the value of a runtime variable, use the following command:
🐧 Linux Hosts
🪟 Windows Hosts
agent variable get {KEY}
For example, the following retrieves a runtime variable named COLOR. 
agent variable get COLOR
Agent-Variable-Get {KEY}
For example, the following retrieves a runtime variable named COLOR. 
Agent-Variable-Get COLOR
Runtime variables via GraphQL
Register variables
The SetSandboxVariable mutation registers the variable with the given key and value on the given participant and host.
mutation setVariable($sandboxID: String!, $hostname: String!, $key: String!, $value: String!) {
    setSandboxVariable(sandboxID: $sandboxID, hostname: $hostname, key: $key, value: $value) {
        key
        value
    }
}
Where $sandboxID is your participant ID and $hostname is the name of your configured host (container or VM).
Retrieve values
The GetSandboxVariable query retrieves a variable value of a provided key.
query getVariable($sandboxID: String!, $hostname: String!, $key: String!) {
    getSandboxVariable(sandboxID: $sandboxID, hostname: $hostname, key: $key) {
        key
        value
    }
}
Where $sandboxID is your participant ID and $hostname is a name of your configured host (container or VM).
Runtime variables in challenge assignments
To retrieve the value of a runtime variable in a challenge assignment use following syntax:
[[ Instruqt-Var key="{KEY}" hostname="{HOSTNAME}" ]]
Where KEY is a key you registered a value with and HOSTNAME is a host where the variable is registered.
You can only access variables via lifecycle scripts, the GraphQL API or assignment markdown. It is not possible to get/set them from a terminal session on a host.
Example
Consider the following challenge assignment, which references a runtime variable named INSTRUQT_TEST_VAR on a host named cloud-client. 
👋 Introduction
===============
​
The following line contains the value of INSTRUQT_TEST_VAR: 
[[ Instruqt-Var key="INSTRUQT_TEST_VAR" hostname="cloud-client" ]]
​
To complete this challenge, press **Next**.
Assuming INSTRUQT_TEST_VAR was registered with a value of TEST123 on the cloud-client host, the assignment text would display TEST123 to the user. 
Video tutorial
Not one for words? Check out this video tutorial on how to use runtime variables. 

Concepts - Previous

Runtime parameters and secrets

Next - Reference

Feature overview

Last modified 1mo ago