# 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](/settings/platform/api.md) or [Lifecycle Scripts](/sandboxes/lifecycle-scripts.md). \
\
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/sandboxes/runtime/runtime-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.