# Runtime variables

## Overview

Runtime variables allow you to use dynamic content in challenge assignments and lifecycle scripts. You can define runtime variables via our [API](https://docs.instruqt.com/settings/platform/api) or [Lifecycle Scripts](https://docs.instruqt.com/sandboxes/lifecycle-scripts). \
\
These variables are configured per participant per host (e.g a user's VM or container) and can only be accessed from the given participant and host.

{% hint style="info" %}
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.
{% endhint %}

## Set variables

#### Define variables <a href="#register-variables" id="register-variables"></a>

You can define variables in lifecycle scripts on Linux and Windows hosts:

{% tabs %}
{% tab title="Linux" %}

```bash
agent variable set <KEY> <VALUE>
```

For example, the following defines a runtime variable named `COLOR` with a value of `RED`.

```bash
agent variable set COLOR RED
```

{% endtab %}

{% tab title="Windows" %}

```
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
```

{% endtab %}
{% endtabs %}

#### Retrieve variables

In order to retrieve the value of a runtime variable, use the following command:

{% tabs %}
{% tab title="Linux" %}

```
agent variable get {KEY}
```

For example, the following retrieves a runtime variable named `COLOR`.

```
agent variable get COLOR
```

{% endtab %}

{% tab title="Windows" %}

```
Agent-Variable-Get {KEY}
```

For example, the following retrieves a runtime variable named `COLOR`.

```
Agent-Variable-Get COLOR
```

{% endtab %}
{% endtabs %}

## Use variables <a href="#runtime-variables-in-challenge-assignments" id="runtime-variables-in-challenge-assignments"></a>

To retrieve the value of a runtime variable in a challenge assignment use following syntax:

```bash
[[ Instruqt-Var key="<KEY>" hostname="<HOSTNAME>" ]]
```

Where `KEY` is a key you registered a value with and `HOSTNAME` is a host where the variable resides.

{% hint style="info" %}
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.
{% endhint %}

#### Example

Consider the following challenge assignment, which references a runtime variable named `INSTRUQT_TEST_VAR` on a host named `cloud-client`.

```markdown
👋 Introduction
===============

The following line contains the value of INSTRUQT_TEST_VAR: 
[[ Instruqt-Var key="INSTRUQT_TEST_VAR" hostname="cloud-client" ]]
```

Assuming `INSTRUQT_TEST_VAR` was registered with a value of `TEST123` on the `cloud-client` host during its setup script, the assignment text would display `TEST123` to the user.