Runtime variables
This page describes how to define runtime variables and use them inside lifecycle scripts or challenge assignments.
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.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.
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
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).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).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.
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. Not one for words? Check out this video tutorial on how to use runtime variables.
Last modified 1mo ago