Pausable tracks

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

This feature is in Beta and is available on request.

Requirements

Supported Resources

The track must use only virtual machines (no containers or website services)

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

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)

🌐 Web UI

For the track:

1. Select the track you wish to make pausable

2. Navigate to the Settings page

3. In the Track Details section, locate "Users can pause track"

4. Toggle the switch to enable pausing

5. Set the Maximum pause duration (1-60 days, default is 7)

6. Click Save

For invites and landing pages:

See the Track invites and Landing pages documentation for configuring pausable tracks when sharing content.

💻 Instruqt CLI

1. If you have not already done so, pull the track you wish to make pausable:

   instruqt track pull <track-slug>

2. Open the track.yml file and add the pausable parameters:

   pausable: <boolean>
   pausable_ttl: <number> # in seconds

   • Set pausable to true to enable pausing

   • Set pausable_ttl to the maximum pause duration in seconds (e.g., 604800 for 7 days)

   As an example, the file might look like the following:

   slug: example-track
   id: xnlauwy2zewf
   title: Example Track
   ...
   pausable: true
   pausable_ttl: 604800  # 7 days in seconds

3. From within the track directory, push the update to Instruqt:

   instruqt track push

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

Learner Experience

Pausing a Track

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

1. Learner clicks "Pause and exit" button

2. The track enters the "pausing" state (this takes a few minutes)

3. Virtual machines are suspended

4. Progress and state are preserved

5. 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. Continue from the last accessed challenge

Resume Time: Resuming typically takes 1-3 minutes as VMs are restored to their previous state.

Automatic Pausing on Idle

For pausable tracks, the idle timeout system automatically pauses tracks instead of stopping them when learners become inactive:

• Idle Detection: When a pausable track exceeds its idle timeout without activity

• Automatic Pause: The system pauses the track rather than stopping it completely

• Resource Optimization: VMs are suspended to save resources while preserving state

• Resume on Return: Learners can resume from where they left off when they return

Required Settings for Automatic Idle Pausing:

1. Track must be pausable: Set pausable: true in track configuration

2. Pause TTL must be configured: Set pausable_ttl > 0 (e.g., 604800 for 7 days)

3. Idle timeout must be set: Configure idle_timeout in track settings (in seconds)

4. Track must use only VMs: No containers or website services

When all these conditions are met, the idle service will automatically pause the track instead of stopping it when the idle timeout is exceeded.

Pause Duration Reset Behavior

When you pause a track after resuming it, the pause duration timer resets to the full maximum configured value. This means:

• Fresh timer on each pause: Every time you pause, you get the full pause duration allowance

• Example: If the maximum pause duration is set to 7 days:

  • You pause for 3 days, then resume

  • When you pause again, you have another full 7 days available (not the remaining 4 days)

• TTL limitation: While each pause resets the duration, you are still bound by the overall track Time-To-Live (TTL)

  • If you repeatedly pause and resume, the track will eventually expire based on its total TTL

Track States

Pausable tracks introduce additional states:

State	Description
pausing	Track is being paused (VMs are suspending)
paused	Track is paused and can be resumed
resuming	Track is being resumed (VMs are restoring)

FAQs

Can all tracks be made pausable?

No, only tracks that exclusively use virtual machines can be made pausable. Tracks containing containers or website services cannot be paused due to technical limitations. Cloud accounts can be used, but they will remain active while paused.

What happens to cloud accounts when a track is paused?

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.

How long can a track remain paused?

You can configure the maximum pause duration (TTL) from 1 to 60 days. The default is 7 days. After the TTL expires, the track will be automatically cleaned up and the learner will need to start over.

Can learners pause tracks in embed mode?

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.

Limitations

Technical Limitations

• Container-based tracks cannot be paused

• Website services prevent pausability

• Embed mode does not support pause/resume

• Maximum pause duration is 60 days

Troubleshooting

Common Issues

"Users can pause track" toggle is disabled

• Check whether the track contains containers or website services

• Remove non-VM resources to enable pausability

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.

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