> For the complete documentation index, see [llms.txt](https://docs.instruqt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.instruqt.com/tracks/manage/pausable-tracks.md).

# Pausable tracks

Enable learners to pause tracks and resume later, preserving their progress and environment state while optimizing resource usage.

{% hint style="info" %}
Available on request. Contact Instruqt Customer Success or Support to enable Pausable Tracks for your team.
{% endhint %}

## Requirements

#### Supported Resources

| Resource Type    | Pausable   | Notes                                    |
| ---------------- | ---------- | ---------------------------------------- |
| Virtual Machines | ✅ Yes      | Fully supported - VMs suspend and resume |
| Containers       | ⚠️ Partial | Remain active while paused (incur costs) |
| Website Services | ⚠️ Partial | Remain active while paused (incur costs) |
| Cloud Accounts   | ⚠️ Partial | Remain active while paused (incur costs) |

{% hint style="warning" %}
Containers and website services will remain active while paused. Pause/resume scripts can be defined for pausing/resuming external resources (e.g. EC2 Instances).
{% endhint %}

## How to use

Using the Instruqt UI or CLI, you can configure pausable tracks:

* **Per track**: Enable pausing for the entire track
* **Per invite or landing page**: Override the track setting when sharing content (This is only possible if the original track has pausing enabled and it meets the requirements above).

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

1. Select the track you want to make pausable.
2. In the **Settings** section, click **Edit**.
3. Click **Additional settings**.
4. Under **Idle & pause behavior**, select **Pausable**.
5. Choose how the track can be paused. At least one of these must stay on:
   * **Auto pause idle users** – the track pauses when the user has been inactive for the number of minutes in **Limit (minutes)**.
   * **Users can pause track** – users can pause the track themselves. Set the maximum pause duration in **Days** and **Hours** (default 3 days, maximum 60 days).
6. Click **Save**.

If you don't see the **Pausable** option, pausable tracks aren't enabled for your organization. Contact your Customer Success Manager or Support.

**For invites and landing pages:**

See the [Track invites](https://docs.instruqt.com/tracks/share/track-invite-links.md) and [Landing pages](https://docs.instruqt.com/tracks/share/landing-pages.md) documentation for configuring pausable tracks when sharing content.
{% endtab %}

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

1. Pull the track to your computer:

   ```
   instruqt track pull <track-slug>
   ```
2. In `track.yml`, set `pausable` to `true` and `pausable_ttl` to the maximum pause duration in seconds (for example, `259200` for 3 days). To also pause the track automatically when a user is idle, add `idle_timeout` in seconds:

   ```yaml
   pausable: true
   pausable_ttl: 259200 # 3 days
   idle_timeout: 1800   # optional: auto pause after 30 minutes of inactivity
   ```
3. From the track directory, push your changes:

   ```
   instruqt track push
   ```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Only virtual machines pause. Everything else keeps running and costing money, unless you add pause and resume scripts. See [Track scripts](https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-software-and-packages-to-a-track).

**Cloud Account Costs**: Cloud accounts (AWS, Azure, GCP) remain active while paused and continue to incur costs. Plan accordingly and communicate this to learners.
{% endhint %}

## Learner Experience

#### Pausing a Track

When learners are in a pausable track, they will see a **"Pause and exit"** button in the track interface.

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2FciUAgmJui5rwEn0QW2ab%2Ftrack-playing-pause-button.png?alt=media&amp;token=d3b22baf-d816-4b5b-a8f7-0775edf56234" alt=""><figcaption></figcaption></figure>

1. Learner clicks "Pause and exit" button
2. The track enters the "pausing" state (this takes a few minutes)
3. Automated Pause script is executed
4. Virtual machines are suspended
5. Progress and state are preserved
6. The learner is redirected to the splash screen

#### Resuming a Track

1. Access the track URL or navigate from an invite or landing page
2. Click the **"Resume"** button on the splash screen
3. The track enters the "resuming" state
4. Virtual machines are restored
5. Automated Resume script is executed.
6. Continue from the last accessed challenge

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2FgkFCj1pOKXYZGRf06rdz%2Fsplash-screen-resume-button.png?alt=media&amp;token=1a374a58-c4a0-4c41-89b4-cab6bc19b9f4" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Resume Time**: Resuming typically takes 1-3 minutes as VMs are restored to their previous state, and resume script is executed.
{% endhint %}

### Automatic pausing on idle

On a pausable track, the idle timeout pauses the track instead of stopping it when a user becomes inactive:

* **Idle detection** – the track is flagged once the user has been inactive for longer than the idle limit.
* **Automatic pause** – the track pauses instead of shutting down completely.
* **Resource optimization** – the pause script runs and the virtual machines are suspended to free up resources, while the track's state is kept.
* **Resume on return** – when the user comes back, they continue where they left off.

To set this up in the Web UI, select **Pausable** under **Idle & pause behavior** and turn on **Auto pause idle users**, then set the limit in minutes.

If you manage the track with the Instruqt CLI, set all three of these in `track.yml`:

1. `pausable: true`
2. `pausable_ttl` greater than 0 (for example, `259200` for 3 days)
3. `idle_timeout` (in seconds)

When all three are set, the track pauses automatically instead of stopping.

### Pause duration reset behavior

When a user resumes a track and pauses it again, the pause timer starts over at the full maximum pause duration:

* **Fresh timer on each pause** – every pause gets the full pause duration you set.
* **Example** – with a maximum of 3 days, a user pauses for 1 day and resumes. When they pause again, they get another full 3 days, not the 2 days that were left.
* **TTL limitation** – each pause resets the pause duration, but the track is still bound by its Time-To-Live (TTL). Pausing and resuming over and over doesn't keep the track alive forever, because it expires when its TTL is reached.

### Track States

Pausable tracks introduce additional states:

| State      | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `pausing`  | Track is being paused (Pause Script running or VMs are suspending)  |
| `paused`   | Track is paused and can be resumed                                  |
| `resuming` | Track is being resumed (VMs are restoring or Resume script running) |

### FAQs

<details>

<summary><strong>Can all tracks be made pausable?</strong></summary>

Yes, any track can be made pausable. However, only virtual machines are actually paused. Cloud accounts, containers and website services will remain active while paused. Pause/resume scripts can be defined for pausing/resuming external resources (e.g. EC2 Instances).

</details>

<details>

<summary><strong>What happens to cloud accounts when a track is paused?</strong></summary>

Cloud accounts (AWS, Azure, GCP) remain active while paused and continue to incur costs. Only the virtual machines are suspended. Communicate this to learners, and consider using lifecycle scripts to minimize resource usage while paused.

</details>

<details>

<summary><strong>What is the maximum pause duration?</strong> </summary>

You can set it between 1 and 60 days, and the default is 3 days. After the pause duration expires, the track is cleaned up and the user has to start again. Tracks that were made pausable before the default changed keep the pause time they already have.

</details>

<details>

<summary><strong>Can learners pause tracks in embed mode?</strong></summary>

No, the pause/resume functionality is not available in embed mode. Learners must access the track through a direct link, invite, or landing page to use the pause feature.

</details>

## Limitations

#### Technical Limitations

* **Embed mode** does not support pause/resume
* **Maximum pause duration** is 60 days

## Troubleshooting

**Pause button not appearing**

* Verify that the track is configured as pausable
* Check that the user is not in embed mode

**Resume fails or takes too long**

* Check whether the pause TTL has expired
* Verify that VM resources are available

## API Reference

For programmatic access to the pausable tracks functionality, see the [Instruqt GraphQL API documentation](https://docs.instruqt.com/settings/platform/api.md).

Key operations include:

* **Query track pausability**: Check if a track is pausable and its configuration
* **Pause play mutation**: Pause a learner's track progress
* **Resume play mutation**: Resume a paused track
* **Track status**: Monitor track states including `pausing`, `paused`, and `resuming`
