agent variable + Instruqt-Var

agent variable set Script side · write

Store a value. Available in subsequent scripts (any host) and to the body via [[ Instruqt-Var ]].

DB_URL="postgresql://..." agent variable set DB_URL "$DB_URL" # Multi-line values OK; single string # limit. For structured payloads use a # JSON broker sidecar instead.

agent variable get Script side · read

Read a value previously set. Common in cleanup to retrieve resource IDs for deletion.

PROJECT_ID=$(agent variable get \ ES_PROJECT_ID) curl -X DELETE \ "https://api.example.com/projects/$PROJECT_ID" \ -H "Authorization: Bearer $TOKEN"

Instruqt-Var in body Body side · interpolation

Render a stored value inside assignment.md. Works inside any string field, including fenced code blocks.

Database URL: `[[ Instruqt-Var key="DB_URL" hostname="db" ]]` ```bash,run psql "[[ Instruqt-Var key=\"DB_URL\" hostname=\"db\" ]]" ```

_SANDBOX_ID gap Auto-injected, but…

_SANDBOX_ID is a shell env var, not in the agent variable store. Bridge it explicitly if the body needs it.

# In track_scripts/setup-workstation: agent variable set SANDBOX_ID \ "$_SANDBOX_ID" # In assignment.md: URL: `https://app-8080-[[ Instruqt-Var key="SANDBOX_ID" hostname="..." ]] .env.play.instruqt.com`

Bridging cloud creds Surface in body

Cloud credential env vars (INSTRUQT_AWS_ACCOUNT_, etc.) are* in the agent variable store automatically — no bridge needed. Bridge synthesized values.

# Auto-injected — works directly: [[ Instruqt-Var key="INSTRUQT_AWS_ACCOUNT_LAB_ACCOUNT_ID" hostname="cloud-client" ]] # Synthesized values need a bridge: agent variable set CONSOLE_URL \ "https://${ACCOUNT_ID}.signin.aws.amazon.com"

Cross-host coordination Single string limit

Agent variables are visible to every host. For passing one or two values between hosts, this is the lightest mechanism.

# On the leader VM: TOKEN=$(generate_token) agent variable set CLUSTER_TOKEN \ "$TOKEN" # On a peer VM (later setup or # challenge): TOKEN=$(agent variable get \ CLUSTER_TOKEN) join_cluster --token "$TOKEN"

For structured payloads: use a JSON broker sidecar (HTTP server on a port returning JSON). Single-string keys get awkward fast for multi-field state.

Notes

Auto-injected variables that are in the store: all INSTRUQT_, INSTRUQT_AWS_ACCOUNT_, INSTRUQT_AZURE_SUBSCRIPTION_, INSTRUQT_GCP_PROJECT_, INSTRUQT_AUTH_TOKEN. Reference these directly in [[ Instruqt-Var ]] without a bridge.
Auto-injected variables that aren't: _SANDBOX_ID and _SANDBOX_DNS. Shell env only. Bridge with agent variable set if the body needs them.
The hostname attribute: required in [[ Instruqt-Var ]]. The platform looks up the value on the named host. The hostname is any container or VM declared in config.yml.
Pre-populating .bash_history: when setup runs a command on the learner's behalf (e.g., vault token create) but a check script greps history for proof-of-attempt, append the literal command: echo "vault token create" >> /root/.bash_history. Surfaces the command via Up arrow and unblocks the check.
CRLF sanitization: secret values delivered with trailing \r\n (Windows authoring) break HTTP headers. Strip with tr -d '\r\n' before using as an Authorization value.
See also: Cookbook Recipe 34 (agent variable cross-host hand-off), Recipe 40 (JSON broker sidecar for structured cross-VM payload).