# Sandbox presets

## Overview

Sandbox presets allow you to share a single sandbox configuration across multiple tracks. Sandbox presets can contain everything a regular sandbox might have. There are two main reasons to implement presets:

* Standardization: Prevent sandbox configurations drift across multiple tracks.
* *Shared hot start pools:* Have multiple tracks pull from the same hot start pool. 

## Create sandbox presets

You can create sandbox presets using the Web UI or the Instruqt CLI.

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Sandbox presets**.
2. Click **Create a new preset**.
3. Input a **Name** for the preset.
4. Input a **Description** for the preset.
5. Add hosts, cloud accounts, scripts, or secrets to the preset. 
6. Click **Save to drafts**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Run the following command to create a sandbox preset:

   ```
   instruqt sandbox create
   ```
2. Input a preset name:

   ```
   ==> Name: <PRESET_NAME>
   ```
3. Change into the newly created preset directory:

   ```
   cd <PRESET_NAME>
   ```
4. Modify the `config.yml` file and create scripts in the `scripts` directory, as needed.
5. Push the preset to Instruqt:

   ```
   instruqt sandbox push
   ```

{% endtab %}
{% endtabs %}

## Publish sandbox preset drafts

You can publish sandbox presets using the Web UI or the Instruqt CLI.

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Sandbox presets**.
2. Click the **Drafts** tab
3. Either click **Publish** on the chosen draft or click on the draft and then **Save and publish** on the next page.
4. Enter a **Commit message**. (optional)
5. Click **Yes, publish**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Run the following command to publish a sandbox preset:

   ```bash
   instruqt sandbox publish --message="My great changes"
   ```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Once a draft is published all tracks using the preset will be updated to use the latest published version and all shared hot-start pools will be drained and provisioned with the new published version.
{% endhint %}

## Use sandbox presets

You can configure tracks to use presets using the Web UI or the Instruqt CLI.

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Sandbox presets**.
2. Find your preset in the list of published presets. If a version has not been published take a look under the **drafts** tab.
3. Note the slug under the name and version of the preset, prefixed with a forward slash.<br>

   <figure><img src="/files/K2aA6OG4o2K0k1Uf4Bra" alt=""><figcaption></figcaption></figure>
4. Next, click the track you want to use the preset in.
5. Under **Manage Track**, click **Configure sandbox**.
6. Click **Use preset.**
7. Click **Proceed and discard edits.**
8. Select the preset you want to use for the track and click **Use selected preset.**
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Pull the track you wish to add a preset to. [See how here. ](/tracks/manage/pull-a-track.md)
2. Change into the track directory.
3. Modify the `track.yml` file by adding the following field:

   ```bash
   sandbox_preset: <INSERT_PRESET_SLUG_HERE>
   ```
4. Remove the tracks `config.yml` and `track_scripts` file and directory, respectively.&#x20;
5. Push the track to Instruqt:

   ```bash
   instruqt track push
   ```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Using a preset may affect existing challenge tabs and lifecycle scripts on the track as the sandbox resources and hosts may differ from the tracks previous config. Double check your work!
{% endhint %}

## Update sandbox presets

You can update presets using the Web UI or the Instruqt CLI.

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Sandbox presets**.
2. Under **Published** tab click **Edit** on the preset you would like to make changes too.
3. Make the desired changes to the sandbox preset.
4. Either click **Save to drafts** if the preset is not ready for use, or click **Save and publish**.
5. Enter a **Commit message**. *(*&#x6F;ptiona&#x6C;*)*&#x20;
6. Click **Yes, publish**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Determine the slug of the sandbox preset you want to update. See [Using sandbox presets](#using-sandbox-presets).&#x20;
2. Open a terminal.
3. Enter the following command, using the slug determined in step 1:

   ```
   instruqt sandbox pull <SANDBOX_PRESET>
   ```
4. Change into the preset directory, and modify as needed.
5. Push the changes to Instruqt:

   ```
   instruqt sandbox push
   ```
6. Once changes are tested, publish the preset:

   ```bash
   instruqt sandbox publish --message="My message"
   ```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
When using the `pull` command the latest version of a sandbox preset will be fetched. If there is a draft version the draft will be fetched, if there is no draft the published version will be fetched.
{% 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/sandboxes/manage/build-sandbox-presets.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.