# Configuration files

## Overview

Instruqt tracks are [Infrastructure-as-Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) artifacts and are made up of configuration files that contain all the properties and settings for tracks in [YAML](https://yaml.org/) and [Markdown](https://en.wikipedia.org/wiki/Markdown) format. You manage these files either from Web UI or Instruqt CLI. For example, the configuration file `track.yml` sets track characteristics and can look something like this:

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

```yaml
slug: mytrack
id: baekpuxv2m5g
type: track
title: MyTrack
teaser: Get started quickly with just one container-based sandbox host.
description: Get started quickly with a container-based sandbox host. Choose a container
  when you need a fast, lightweight Linux system.
icon: https://cdn.instruqt.com/assets/templates/ubuntu.png
tags: []
owner: myteam
developers:
- developer@content.com
maintenance: true
show_timer: true
skipping_enabled: true
```

{% endtab %}
{% endtabs %}

You probably recognize tracks details like `title` and `teaser` as you set them from Web UI. But you can also set these properties by manipulating the `track.yml` file from your code editor and push your changes with Instruqt CLI to the Instruqt platform.

{% hint style="warning" %}
YAML files use spaces for indentation. Use 2 or 4 spaces for indentation, but **no tabs**.
{% endhint %}

{% hint style="info" %}
To learn how to use these files, read the [Edit locally ](/tracks/manage/pull-a-track.md)docs.
{% endhint %}

If you created a track with Instruqt CLI or pulled a track to your machine, you will find the configuration files inside the track directory and subdirectories:

```markdown
# Example directory layout with track configuration files
.
├── 01-first-challenge          # First challenge
|   ├── assignment.md           # Challenge assignment and configuration
│   ├── check-host01            # Challenge lifecycle scripts
│   └── solve-host01
├── 02-second-challenge         # Second challenge
|   ├── assignment.md
│   ├── setup-host01
│   ├── check-host01
│   ├── solve-host01
│   └── cleanup-host01
├── track_scripts               # Track lifecycle scripts
│   ├── setup-host01
│   └── cleanup-host01
├── config.yml                  # Sandbox configuration
└── track.yml                   # Track configuration
```

## Track level files

Generally speaking, there are four file types at a track level:

{% tabs %}
{% tab title="config.yaml" %}
The `config.yml` file contains the sandbox definition of a track.

```yaml
version: "3"
# container definitions
containers:
- name: <hostname>
  image: <container_image>
  shell: <shell_type>
  memory: <memory_mb>
  
# website host definitions
virtualbrowsers:
- name: <hostname>
  url: <website_urls>

# virtual machine definitions
virtualmachines:
- name: <hostname>
  image: <gcp_project>/<image_name>
  shell: <shell_type>
  machine_type: <machine_size>

# cloud account definitions
gcp_projects:
- name: <project_name>
  services:
  - <service_name>.googleapis.com
  roles: 
  - roles/<role_name>
aws_accounts:
- name: <account_name>
  managed_policies:
  - arn:aws:iam::aws:policy/<policy_name>
azure_subscriptions:
- name: <subcription_name>
  roles:
  - <role_name>
  
# sandbox secrets
secrets:
- name: <secret>
```

{% endtab %}

{% tab title="track.yml" %}
The `track.yml` file contains the track metadata and settings.

```markdown
slug: <track_slug>
id: <track_id>
title: <track_title>
teaser: <track_teaser>
description: <track_description>
icon: <path_to_icon>
tags: [<tag>,<tag>]
owner: <instruqt_team_name>
developers:
- <developer_email>
idle_timeout: <value_in_seconds>
timelimit: <value_in_seconds>
lab_config:
  extend_ttl: <value_in_seconds>
  sidebar_enabled: <boolean>
  feedback_recap_enabled: <boolean>
  feedback_tab_enabled: <boolean>
  loadingMessages: <boolean>
  theme:
    name: <modern-dark_or_original>
  default_layout: <AssignmentRight_or_AssignmentLeft_or_AssignmentBottom>
  default_layout_sidebar_size: <value_between_25_100>
  override_challenge_layout: <boolean>
```

{% endtab %}

{% tab title="setup-host" %}
The `setup-<hostname>` file is the script that runs after a track stops.

{% code title="Example script" %}

```bash
#!/bin/bash
set -euxo pipefail

# Wait for the Instruqt host bootstrap to finish
until [ -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
do
    sleep 1
done

...more commands...
```

{% endcode %}

{% hint style="info" %}
Instruqt scripts can be written in any language, including PowerShell and Python.
{% endhint %}
{% endtab %}

{% tab title="cleanup-host" %}
The `cleanup-<hostname>` file is the script that runs once a host is provisioned.

{% code title="Example script" %}

```bash
#!/bin/bash
set -euxo pipefail

curl -X POST https://my-api.com/delete/resource/X
```

{% endcode %}

{% hint style="info" %}
Instruqt scripts can be written in any language, including PowerShell and Python.
{% endhint %}
{% endtab %}
{% endtabs %}

<table><thead><tr><th width="173">File name</th><th>Description</th></tr></thead><tbody><tr><td><code>config.yml</code></td><td>Contains the sandbox definition in YAML.</td></tr><tr><td><code>track.yml</code></td><td>Contains the track definition in YAML.</td></tr><tr><td><code>setup-host</code></td><td>Contains a script for setting up the track.</td></tr><tr><td><code>cleanup-host</code></td><td>Contains a script for cleaning up the track.</td></tr></tbody></table>

{% hint style="info" %}
For more information on Track scripts, [read these docs](/sandboxes/lifecycle-scripts/add-software-and-packages-to-a-track.md).
{% endhint %}

## Challenge level files

<table><thead><tr><th width="184">File name</th><th>Description</th></tr></thead><tbody><tr><td><code>assignment.md</code></td><td>Contains challenge definition in YAML, learner assignment in markdown.</td></tr><tr><td><code>setup-host</code></td><td>Script for setting up the challenge.</td></tr><tr><td><code>check-host</code></td><td>Script for checking if the learner solved the challenge.</td></tr><tr><td><code>solve-host</code></td><td>Script for automatically solving a challenge when a learner skips.</td></tr><tr><td><code>cleanup-host</code></td><td>Script for cleaning up the challenge.</td></tr></tbody></table>

{% hint style="info" %}
For more information on challenge scripts, [read these docs.](/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution.md)
{% endhint %}


---

# 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/reference/cli/configuration-files.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.