Exec

The Exec resource lets you execute scripts and commands either locally on the host machine or remotely inside containers. It provides a flexible way to automate environment setup, system configuration, and custom workflows as part of your lab sandbox, without needing to write configuration files.

Through the UI, you can define exec settings such as the script content, execution mode (local or remote), timeout, environment variables, and output handling. For remote execution, you can either create a new container or target an existing one, with support for network attachments and volume mounts.

Exec resources are ideal for tasks like installing dependencies, configuring services, running build scripts, and initializing databases during lab setup.

For more information on the exec sandbox resource, please refer to the Exec Reference documentation.

Migrating Track setup scripts

For sandbox setup commands previously kept in a Track-level setup script, use Exec resources in Labs. Do not copy the entire script unchanged: first separate custom setup from work that Lab resources already handle.

Remove the Track bootstrap wait

Labs do not create /opt/instruqt/bootstrap/host-bootstrap-completed. Remove Track setup loops such as this one before running the migrated script:

# Remove this Track-only wait from Lab scripts.
until [ -f /opt/instruqt/bootstrap/host-bootstrap-completed ]; do
  sleep 1
done

The script cannot progress past this loop; increasing its timeout does not fix the missing marker. Do not create the marker manually or replace the loop with a fixed sleep: neither proves that the environment is ready. Instead, express resource ordering with references or depends_on, and check the service you actually need with native health checks, as described below. A VM’s Startup Script runs after the VM agent is reachable; it does not need this Track bootstrap wait.

Keep only the custom setup in Exec

• Waiting for a service: configure the container or VM’s native Health Checks instead of carrying over polling loops or fixed sleeps. Use HTTP, TCP, or an Exec health probe to test readiness. A probe checks readiness; it must not perform setup.
• Waiting for another resource: use resource references in the Lab configuration. For example, an Exec’s Target establishes a dependency on that container. HCL authors can use depends_on for ordering that is not expressed by a reference. Commands or file paths inside a shell script do not create resource dependencies.
• Writing static configuration with heredocs: keep the configuration as a file in the lab repository, for example files/app.conf, and mount or copy it to the resource that needs it. See Files and container volumes.
• Generating configuration with variable values: use a Template resource, then reference its output from the consuming resource instead of generating the file in a setup script.
• Custom initialization: keep commands such as database seeding or application configuration in an Exec script. Split scripts when they have different targets or dependencies, not simply to put every command in its own resource.

For example, a script that writes an application config, waits for a database, and seeds it becomes a configuration file or Template, a database health check, and an Exec containing only the seed commands. The database health check must be able to pass before the dependent seed Exec runs.

Choose where the remaining commands run

Open Sandbox → + → Exec and choose one of the execution modes. Local runs on the sandbox host, not on the VM or container you used as a Track host. To run commands inside an existing container, choose Remote (existing resource) and select that container as Target.

For setup that must run inside a VM at boot, use the VM’s Startup Script; the editor’s Target list offers only containers. Setup tied to a user’s task belongs in a task condition’s Setup script, not a sandbox Exec.

Check paths, available commands, environment variables, and dependencies for each destination. Save your changes and test a fresh lab session to confirm the environment is ready before the user starts working.

Execution modes

The exec resource supports three distinct execution modes:

• Local: runs the script directly on the host machine.
• Remote (new container): creates a new container from a specified image and runs the script inside it. Supports network attachments and volume mounts.
• Remote (existing resource): runs the script inside an already running container by selecting it from a list of existing ones. Only available when your lab already contains a container resource.

The Working Directory, Timeout, and Run As fields are shown for every mode. The Daemon switch is the only field gated by mode: it only appears in local mode.

Creating an Exec resource

Exec resources can be created in the Sandbox tab. To create a new Exec resource, navigate to the Sandbox tab and click the + button. Select Exec from the dropdown menu.

Start by naming the exec resource. Note that this is an internal name. You must provide a script to execute, and optionally configure the execution mode, timeout, environment variables, and other settings.

Setting the script

The Script field is the core of the exec resource, where you write your script directly in the code editor.

Tip

You can write key-value pairs to the $EXEC_OUTPUT file to pass data to other resources.

echo "STATUS=completed" >> $EXEC_OUTPUT

Choosing an execution mode

By default, the exec resource runs in Local mode on the host machine. To run the script remotely, choose one of:

• Remote (new container) to create a new container for execution.
• Remote (existing resource) to run the script inside an existing container.

Note

The Remote (existing resource) option is only available when your lab already contains a container resource. You must create a container before you can target it for remote execution.

Editing an Exec resource

To edit an exec resource, select it from the list of existing sandboxes in the Sandbox tab. Click on the exec resource you want to edit, make your changes in the configuration panel, and then click Add changes to save your updates. See Editing & Publishing for how changes are reviewed and published.

Configuration

Script and environment

Field	Required?	Default	Description
Script	✓		Script content to execute
Environment			Key-value pairs for environment variables

Configuration

These fields are shown for all three execution modes.

Field	Required?	Default	Description
Working Directory			Directory to execute the script in
Timeout			Maximum execution time, for example 30s, 5m

The Daemon switch is the exception: it’s only shown in local mode.

Field	Required?	Default	Description
Daemon		false	Run the script as a background daemon process

In both remote modes the platform waits for the script itself to exit, up to Timeout — a script that starts a long-running process must detach it and exit. See Long-Running Scripts.

This section also includes a Run As group, shown for all three modes:

Field	Required?	Default	Description
User			Username or user ID
Group			Group name or group ID

Remote execution (new container)

These fields appear only in Remote (new container) mode.

Container

Field	Required?	Default	Description
Name	✓		Docker image name with optional tag

Selecting a custom image also reveals Username and Password fields for pulling from a private registry.

Network

Field	Required?	Default	Description
ID	✓		Reference to a network resource
IP Address			Static IP address (auto-assigned if not set)

Note

Networks must be created before they can be assigned to an exec resource. For more information on creating a network resource, please refer to the Network documentation.

Volume

Field	Required?	Default	Description
Source	✓		Source path or volume name
Destination	✓		Mount path inside the container
Read Only		false	Mount the volume as read-only

Remote execution (existing container)

This field appears only in Remote (existing resource) mode.

Field	Required?	Default	Description
Target	✓		Reference to an existing container resource

Summary

The Exec resource provides flexible script execution capabilities for automating setup tasks, system configuration, and custom workflows in your lab sandbox. You can run scripts locally on the host or remotely inside containers, either by creating a new container from an image or by targeting an existing one.

With support for environment variables, output capture, timeouts, and advanced container options like volumes, networks, and user configuration, exec resources give you fine-grained control over your lab’s automation without needing to write configuration files.