Virtual Machine

Defined insandboxes.hcl

The vm resource defines a virtual machine that runs as part of your lab sandbox environment. VMs provide full operating system compute for labs that need system services, OS-level configuration, extra disks, or workloads that do not fit a container-only design.

Use Cases

As a lab author, you can use VMs to create richer sandbox environments:

• Full Operating Systems: Run workloads that need a complete Linux environment instead of a single container process
• System Configuration Labs: Teach package installation, service management, networking, or disk setup
• Nested Runtime Labs: Provide VM images that include Docker, Kubernetes, or other platform tooling
• Stateful Services: Attach additional disks for databases, data directories, or other storage-heavy exercises

Use a VM when the lab experience depends on OS behavior. Use a container when a lighter process-isolated runtime is enough.

HCL Syntax

Basic Syntax

resource "vm" "ubuntu" {
  image {
    name = "ubuntu:24.04"
  }
}

Full Syntax

resource "network" "main" {
  subnet = "10.50.0.0/24"
}

resource "vm" "ubuntu" {
  config {
    arch = "x86_64"
  }

  image {
    name     = "ubuntu:24.04"
    username = "registry-user"
    password = variable.registry_token
  }

  resources {
    cpu    = 2
    memory = 2048
  }

  environment = {
    GREETING = "hello"
  }

  dns            = ["1.1.1.1"]
  startup_script = <<-EOF
    #!/bin/sh
    apt-get update
    apt-get install -y nginx
  EOF

  network {
    id         = resource.network.main.meta.id
    ip_address = "10.50.0.10"
    aliases    = ["web"]
  }

  disk {
    destination = "/data"
    size        = 20
  }

  volume {
    source      = "./shared"
    destination = "/mnt/shared"
    read_only   = true
  }

  port {
    local           = "8080"
    host            = "8080"
    protocol        = "tcp"
  }

  port_range {
    range       = "3000-3010"
    enable_host = true
    protocol    = "tcp"
  }

  health_check {
    timeout = "30s"

    tcp {
      address = "localhost:8080"
    }
  }
}

Resource Structure

vm
├─ config
│  └─ arch
├─ image (required)
│  └─ name, username, password
├─ resources
│  └─ cpu, memory
├─ environment
├─ dns[]
├─ startup_script
├─ networking
│  └─ network[] (repeatable)
│     └─ id, ip_address, aliases
├─ storage
│  ├─ disk[] (repeatable)
│  │  └─ destination, size
│  └─ volume[] (repeatable)
│     └─ source, destination, type, read_only
├─ port exposure
│  ├─ port[] (repeatable)
│  │  └─ local, host, protocol
│  └─ port_range[] (repeatable)
│     └─ range, enable_host, protocol
└─ monitoring
   └─ health_check
      ├─ timeout
      ├─ http[] (address, method, body, headers, success_codes)
      ├─ tcp[] (address)
      └─ exec[] (command, script, exit_code)

Fields

Field	Type	Required	Description
config	block	—	Low-level machine settings for the VM, such as which CPU architecture it emulates
image	block	✓	The base image the virtual machine boots from. This defines the operating system and preinstalled software available to learners.
resources	block	—	Set how much CPU and memory the virtual machine can use
disk	block	—	Attach additional disk images to the VM, for example to ship a prepared dataset or a second filesystemrepeatable
volume	block	—	Share files from the lab repository into the VM, or persist data written by the VMrepeatable
network	block	—	Connect your container to a specific network to enable communication between containers or servicesrepeatable
port	block	—	Expose specific ports so learners can access web apps, APIs, or services running in the containerrepeatable
port_range	block	—	Specify a range of ports to open for applications that require multiple consecutive ports, such as clusters or debugging toolsrepeatable
environment	map(string)	—	Set environment variables to pass configuration values, API keys, or secrets to the VM
startup_script	string	—	Shell script that runs automatically when the VM boots. Use it to install packages, configure the OS, or set up your lab environment.
dns	list(string)	—	Configure DNS servers or custom hostnames for your VM to resolve network addresses ConstraintsMust be a valid IP address
health_check	block	—	Define checks to confirm that your VM is running and responsive

Config

vm→Config

VM configuration

Field	Type	Required	Description
arch	string	—	CPU architecture of the VM. Use x86_64 for standard Intel/AMD hardware, or aarch64 for ARM-based environments such as AWS Graviton.

Image

vm→Image

VM image configuration

Field	Type	Required	Description
name	string	✓	Full Docker image reference, including the registry and an optional tag. Include a specific tag to ensure consistent lab environments. ConstraintsMust be a valid Docker image reference (e.g. ubuntu:24.04, docker.io/hashicorp/vault:1.14)
username	string	—	Only required for private Docker registries. Leave empty for public images.
password	string	—	Only required for private Docker registries. Leave empty for public images.

Resources

vm→Resources

Resource allocation for the VM

Field	Type	Required	Description
cpu	number	—	Set the number of CPU cores for this VM
memory	number	—	Specify how much memory to allocate to this VM

Disk

vm→Disk

Disk images attached to the VM

Field	Type	Required	Description
type	string	—	Disk image format. qcow2 is the most common for QEMU and supports snapshots; raw is a simple byte-for-byte image
source	string	—	URL or local path to the disk image file
size	string	—	Set the maximum capacity of this disk. Applied when expanding a base image.
destination	string	—	Absolute path where the disk is mounted inside the VM
readonly	bool	—	Prevent the VM from writing to this disk. Use it to keep a shared base image unchanged.

Volume

vm→Volume

Volume mounts for the VM

Field	Type	Required	Description
source	string	✓	The path to mount into the VM. Can be relative to the file declaring the VM (`./`) or absolute (`/usr/local/bin`).
destination	string	✓	Absolute path inside the VM where the source is mounted
read_only	bool	—	Prevent the VM from writing to this mount

Network

vm→Network

Network interfaces for the VM

Field	Type	Required	Description
id	string	✓	ID of the network to attach the container
ip_address	string	—	Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned.
aliases	list(string)	—	Aliases allow alternate names to specified for the container

Port

vm→Port

Port mappings for the VM

Field	Type	Required	Description
local	number	✓	The local port in the container ConstraintsMinimum 1; Maximum 65535
host	number	—	The host port to map the local port to ConstraintsMinimum 1; Maximum 65535
protocol	string	—	The protocol to use when exposing the port Allowedtcp udp Defaulttcp

Port Range

vm→Port Range

Range of ports to expose

Field	Type	Required	Description
range	string	✓	The port range to expose, e.g., `8080-8082` would expose the ports `8080`, `8081`, `8082` ConstraintsRange format is "<number>-<number>"
enable_host	bool	—	Expose the port range on the host
protocol	string	—	The protocol to use when exposing the port Allowedtcp udp Defaulttcp

Health Check

vm→Health Check

Health checks for the VM

Field	Type	Required	Description
timeout	string	✓	The maximum duration to wait before marking the health check as failed. Expressed as a Go duration, e.g. 1s = 1 second, 100ms = 100 milliseconds. Default30s ConstraintsMust be a valid duration (e.g. 30s, 5m)
exec	block	—	Runs a command or script inside the VM. The check passes when the command exits with code 0.repeatable
http	block	—	Sends an HTTP request to the address and passes when the response matches the expected success codesrepeatable
tcp	block	—	Attempts to open a TCP connection to the address. If the connection opens, the check passes.repeatable

Exec Health Check

vm→Health Check→Exec Health Check

Execute command health check

Field	Type	Required	Description
command	list(string)	—	The command to run, given as the executable followed by its arguments. Use either a command or a script, not both.
script	string	—	An inline shell script to run instead of a single command. Must start with a shebang, e.g. #!/bin/bash.
exit_code	number	—	The exit code that counts as healthy. Defaults to 0.

HTTP Health Check

vm→Health Check→HTTP Health Check

HTTP health check

Field	Type	Required	Description
address	string	✓	The URL to check, health check expects a HTTP status code to be returned by the URL in order to pass the health check
method	string	—	HTTP method to use when executing the check
body	string	—	HTTP body to send with the request
headers	map(list(string))	—	HTTP headers to send with the check
success_codes	list(number)	—	HTTP status codes returned from the endpoint when called. If the returned status code matches any in the array then the health check will pass.

TCP Health Check

vm→Health Check→TCP Health Check

TCP health check

Field	Type	Required	Description
address	string	✓	Host and port to connect to, e.g. localhost:5432. The check passes as soon as the connection is accepted.

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
image.id	string	Unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID.
network[].name	string	Name will equal the name of the network as created by jumppad
network[].assigned_address	string	AssignedAddress will equal if IPAddress is set, else it will be the value automatically assigned from the network

Examples

Basic VM

resource "vm" "ubuntu" {
  image {
    name = "ubuntu:24.04"
  }
}

VM with Network and Terminal Access

resource "network" "main" {
  subnet = "10.50.0.0/24"
}

resource "vm" "devbox" {
  image {
    name = "ubuntu:24.04"
  }

  resources {
    cpu    = 2
    memory = 2048
  }

  network {
    id         = resource.network.main.meta.id
    ip_address = "10.50.0.10"
  }

  startup_script = <<-EOF
    #!/bin/sh
    apt-get update
    apt-get install -y curl jq
  EOF
}

resource "terminal" "devbox" {
  target = resource.vm.devbox
  shell  = "/bin/bash"
}

VM with Disk and Service Tab

resource "network" "main" {
  subnet = "10.50.0.0/24"
}

resource "vm" "web" {
  image {
    name = "ubuntu:24.04"
  }

  disk {
    destination = "/var/lib/app"
    size        = 20
  }

  port {
    local = "8080"
    host  = "8080"
  }

  network {
    id = resource.network.main.meta.id
  }

  health_check {
    http {
      address = "http://localhost:8080/health"
    }
  }
}

resource "service" "web" {
  target = resource.vm.web
  port   = 8080
}

Best Practices

1. Choose the right compute type: Use VMs for full OS behavior and containers for lightweight application runtimes
2. Attach a network for interactive labs: Terminal access, service tabs, startup scripts, and exec health checks depend on VM reachability
3. Size resources deliberately: VMs need enough CPU and memory for the guest operating system and your lab workload
4. Use explicit image tags: Pin images to stable versions for repeatable lab runs
5. Make startup scripts idempotent: Startup scripts should handle reruns and partially completed setup safely
6. Use disks for durable paths: Mount additional disks at application data paths and avoid reserved system paths
7. Expose only needed ports: Map the smallest set of ports required for the learner experience