Virtual Machine

A Virtual Machine resource lets you create and configure VM-based compute for a lab sandbox. Use a VM when your lab needs a full operating system environment, OS-level services, package installation, system configuration, or workloads that do not fit a container-only model.

Through the UI, you can define the VM image, resources, startup script, environment variables, networking, ports, disks, volumes, and health checks without writing configuration files. You can also connect VMs to sandbox networks and use them as targets for terminal and service tabs.

VMs are useful for labs that need stronger OS isolation or a closer match to real infrastructure while still using the same sandbox workflow as containers and networks.

Creating a Virtual Machine resource

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

Start by naming the VM. This name is internal and becomes the VM hostname at runtime. The form shows the computed hostname so you can see how other sandbox resources can reach the VM.

Choose an image from the preset list or enter your own public or private image. For private images, add the registry username and password fields in the Image section.

Editing a Virtual Machine resource

To edit a Virtual Machine resource, select it from the list of existing sandbox resources in the Sandbox tab. Click the VM 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.

Form sections

The Virtual Machine form is organized into collapsible sections. The Image and Resources sections are expanded by default. All other sections are collapsed and can be expanded by clicking on them.

1. Image (expanded by default)

Field	Required?	Default	Description
Image	✓		VM image to boot
Username			Optional username for pulling a private image
Password			Optional password or token for pulling a private image

2. Resources (expanded by default)

Field	Required?	Default	Description
Memory		2048	Memory allocated to the VM in MB
CPU		2	CPU allocation for the VM

3. Startup Script (collapsed)

Field	Required?	Default	Description
Startup Script			Script that runs once when the VM boots

Note

Startup scripts run through the VM agent after the VM is reachable. Attach the VM to a network when your lab depends on startup scripts.

4. Environment Variables (collapsed)

Field	Required?	Default	Description
Environment Variables			Key-value pairs exported into the VM environment

5. DNS Servers (collapsed)

Field	Required?	Default	Description
DNS Server			Optional DNS server IP address used by the VM

6. Networks (collapsed)

Field	Required?	Default	Description
Network	✓		Existing network resource to attach to the VM
IP Address			Optional static IP address in the selected network
Name			Optional name for this VM network attachment
Aliases			Optional DNS aliases for the VM on the selected network. Resolve an alias from a VM by its FQDN (<alias>.sandbox.internal).

Note

Networks must be created before they can be assigned to a VM. For more information, see the Network documentation.

7. Ports (collapsed)

Field	Required?	Default	Description
Local	✓		Port the app listens on inside the VM
Host			Optional host port to bind
Protocol		tcp	Protocol type: TCP or UDP

8. Port Ranges (collapsed)

Field	Required?	Default	Description
Range	✓		Consecutive port range to expose, for example 3000-3010
Enable host		false	Map the range to host ports
Protocol		tcp	Protocol type: TCP or UDP

9. Disks (collapsed)

Field	Required?	Default	Description
Destination			Absolute path inside the VM where the disk is mounted
Size			Disk size, for example 20G
Source			Source image URL or path
Type			Disk type, for example qcow2 or raw
Readonly		false	Mount the disk as read-only

10. Volumes (collapsed)

Field	Required?	Default	Description
Source	✓		Path on the host or managed volume name
Destination	✓		Intended path inside the VM
Read only		false	Attach the share as read-only

11. Health Checks (collapsed)

Field	Required?	Default	Description
Timeout		30s	Health check timeout

Health checks support three modes:

HTTP

Field	Required?	Default	Description
Address	✓		Health check URL
Method		GET	HTTP method
Body			Request body
Headers			HTTP headers
Success codes		200	Expected success codes

TCP

Field	Required?	Default	Description
Address	✓		Health check address

Exec

Field	Required?	Default	Description
Command			Health check command
Script			Health check script
Exit code		0	Expected exit code

Summary

The Virtual Machine resource adds full-OS compute to your sandbox. Use it for labs that need VM behavior, system services, disks, or runtime setup beyond what a container provides.

For most interactive VM labs, attach the VM to a sandbox network, configure the required ports or service tabs, and add a terminal tab when users need shell access.