Layout

Defined inlayouts.hcl

The layout resource defines the visual structure of the lab UI through columns and rows. Layouts organize how tabs (terminal, service, editor, etc.) and instructions are displayed to users.

Use Cases

As a lab author, you use layouts to create optimal learning interfaces:

• Content Organization: Structure the lab interface to present instructions alongside relevant tools and terminals in a logical arrangement
• Multi-Tool Scenarios: Create layouts that support complex scenarios requiring multiple terminals, editors, or service interfaces simultaneously
• Screen Real Estate Management: Optimize the use of available screen space to maximize both instruction visibility and hands-on tool access

Layouts ensure that the lab interface supports rather than hinders the learning experience by presenting information and tools effectively.

HCL Syntax

Basic Syntax

resource "layout" "name" {
  column {
    instructions {}
  }

  column {
    tab "terminal" {
      target = resource.terminal.main
    }
  }
}

Full Syntax

resource "layout" "name" {
  column {
    width = "percentage"

    tab "name" {
      target = resource.type.name
      title = "Display Title"
      active = true
      visible = true
      closeable = false
      movable = false
    }

    instructions {
      title = "Instructions"
      active = false
    }

    row {
      height = "percentage"
      # nested content
    }
  }
}

Fields

Field	Type	Required	Description
column	block	—	Top-level columns in the layoutrepeatable

Column

layout→Column

Top-level columns in the layout

Field	Type	Required	Description
width	string	—	Set the width of this column, as a bare integer without a unit: '50', not '50%'. Columns without an explicit width share the remaining space equally.
tab	block	—	Tabs within this columnrepeatable
instructions	block	—	Instructions panel within this column
row	block	—	Rows nested within this columnrepeatable

Tab

layout→Column→Tab

Tabs within this column

Field	Type	Required	Description
slug	label	—	The unique identifier for this tab, used to reference it in HCL configuration and from other resources
title	string	—	Display title for the tab
target	referenceterminal, service, editor, note, virtual_browser, external_website, cloud_credentials	✓	Reference to the target resource
active	bool	—	Set this tab as the active (focused) tab when the lab loads
visible	bool	—	Control whether this tab is visible to learners. Hidden tabs still exist but cannot be accessed.
closeable	bool	—	Allow learners to close this tab
movable	bool	—	Allow learners to drag and reposition this tab within the layout

Instructions

layout→Column→Instructions

Instructions panel within this column

Field	Type	Required	Description
title	string	—	Title for the instructions panel
active	bool	—	Whether the instructions panel is active
visible	bool	—	Whether the instructions panel is visible
closeable	bool	—	Whether the instructions panel can be closed
movable	bool	—	Whether the instructions panel can be moved

Row

layout→Column→Row

Rows nested within this column

Field	Type	Required	Description
height	string	—	Set the height of this row, as a bare integer without a unit: '50', not '50%'. Rows without an explicit height share the remaining space equally.
tab	block	—	Tabs within this rowrepeatable
instructions	block	—	Instructions panel within this row
column	block	—	Columns nested within this row (3rd level)repeatable

Tab

layout→Column→Row→Tab

Tabs within this row

Field	Type	Required	Description
slug	label	—	The unique identifier for this tab, used to reference it in HCL configuration and from other resources
title	string	—	Display title for the tab
target	referenceterminal, service, editor, note, virtual_browser, external_website, cloud_credentials	✓	Reference to the target resource
active	bool	—	Set this tab as the active (focused) tab when the lab loads
visible	bool	—	Control whether this tab is visible to learners. Hidden tabs still exist but cannot be accessed.
closeable	bool	—	Allow learners to close this tab
movable	bool	—	Allow learners to drag and reposition this tab within the layout

Instructions

layout→Column→Row→Instructions

Instructions panel within this row

Field	Type	Required	Description
title	string	—	Title for the instructions panel
active	bool	—	Whether the instructions panel is active
visible	bool	—	Whether the instructions panel is visible
closeable	bool	—	Whether the instructions panel can be closed
movable	bool	—	Whether the instructions panel can be moved

Column

layout→Column→Row→Column

Columns nested within this row (3rd level)

Field	Type	Required	Description
width	string	—	Set the width of this column, as a bare integer without a unit: '50', not '50%'. Columns without an explicit width share the remaining space equally.
tab	block	—	Tabs within this nested columnrepeatable
instructions	block	—	Instructions panel within this nested column

Tab

layout→Column→Row→Column→Tab

Tabs within this nested column

Field	Type	Required	Description
slug	label	—	The unique identifier for this tab, used to reference it in HCL configuration and from other resources
title	string	—	Display title for the tab
target	referenceterminal, service, editor, note, virtual_browser, external_website, cloud_credentials	✓	Reference to the target resource
active	bool	—	Set this tab as the active (focused) tab when the lab loads
visible	bool	—	Control whether this tab is visible to learners. Hidden tabs still exist but cannot be accessed.
closeable	bool	—	Allow learners to close this tab
movable	bool	—	Allow learners to drag and reposition this tab within the layout

Instructions

layout→Column→Row→Column→Instructions

Instructions panel within this nested column

Field	Type	Required	Description
title	string	—	Title for the instructions panel
active	bool	—	Whether the instructions panel is active
visible	bool	—	Whether the instructions panel is visible
closeable	bool	—	Whether the instructions panel can be closed
movable	bool	—	Whether the instructions panel can be moved

Layout Structure

The layout resource uses a hierarchical structure:

• Columns: Vertical divisions of the layout
• Rows: Horizontal divisions within columns
• Tabs: Content panels that reference other resources
• Instructions: Special panel for lab instructions

Column Block

layout → column

A column is a vertical panel within the layout. Columns do not have names or IDs - they are anonymous blocks.

Column Fields

Field	Required	Type	Description
width		string	Width of the column as a percentage (e.g., “50”, “33”). Defaults to equal distribution.
tab		block	Tab blocks defining content panels
instructions		block	Instructions panel configuration
row		block	Nested row blocks for further subdivision

Row Block

layout → column → row

A row is a horizontal panel within a column. Like columns, rows are anonymous blocks without names or IDs.

Row Fields

Field	Required	Type	Description
height		string	Height of the row as a percentage. Defaults to equal distribution.
tab		block	Tab blocks defining content panels
instructions		block	Instructions panel configuration
column		block	Nested column blocks for further subdivision

Tab Block

layout → tab

Tabs define the actual content panels within the layout. Each tab must have a name (used as a label) and references a resource.

Tab Fields

Field	Required	Type	Description
name	✓	label	The identifier for the tab, written as the block label: tab “name” { … }. Validator errors refer to it as the tab’s slug.
title		string	Display title for the tab. Defaults to capitalized name.
target	✓	reference to terminal, service, editor, external_website, virtual_browser, note, cloud_credentials	Reference to the resource to display
active		bool	Whether the tab is initially active. Defaults to false.
visible		bool	Whether the tab is visible. Defaults to true.
closeable		bool	Whether users can close the tab. Defaults to false.
movable		bool	Whether users can move the tab. Defaults to false.

Supported Tab Targets

Resource Type	Description	Reference
terminal	Interactive command-line interface	Terminal
service	Web applications and services	Service
editor	Code editing environment	Editor
external_website	External website integration	External Website
virtual_browser	Embedded virtual browser	Web Browser
note	Reference materials and documentation	Note
cloud_credentials	Cloud provider credentials display	Cloud Credentials

Instructions Block

layout → instructions

The instructions block configures the special instructions panel.

Instructions Fields

Field	Required	Type	Description
title		string	Title of the instructions tab. Defaults to “Instructions”.
active		bool	Whether the tab is initially active. Defaults to false.
visible		bool	Whether the tab is visible. Defaults to true.
closeable		bool	Whether users can close the tab. Defaults to false.
movable		bool	Whether users can move the tab. Defaults to false.

Examples

Two Column Layout

resource "layout" "two_column" {
  column {
    width = "50"

    instructions {}
  }

  column {
    width = "50"

    tab "terminal" {
      target = resource.terminal.main
    }
  }
}

Complex Layout with Rows

resource "layout" "complex" {
  column {
    width = "40"

    instructions {}
  }

  column {
    width = "60"

    row {
      height = "70"

      tab "terminal" {
        target = resource.terminal.main
        active = true
      }

      tab "editor" {
        target = resource.editor.code
      }
    }

    row {
      height = "30"

      tab "service" {
        target = resource.service.web
      }
    }
  }
}

Three Column Layout

resource "layout" "three_column" {
  column {
    width = "25"

    instructions {}
  }

  column {
    width = "50"

    tab "terminal" {
      target = resource.terminal.main
      active = true
    }

    tab "terminal2" {
      target = resource.terminal.secondary
    }
  }

  column {
    width = "25"

    tab "notes" {
      target = resource.note.hints
    }
  }
}

Nested Layout

resource "layout" "nested" {
  column {
    width = "30"

    row {
      height = "50"
      instructions {}
    }

    row {
      height = "50"
      tab "notes" {
        target = resource.note.hints
      }
    }
  }

  column {
    width = "70"

    row {
      height = "60"

      column {
        width = "60"
        tab "terminal" {
          target = resource.terminal.main
        }
      }

      column {
        width = "40"
        tab "editor" {
          target = resource.editor.config
        }
      }
    }

    row {
      height = "40"
      tab "service" {
        target = resource.service.app
      }
    }
  }
}

Migration Notes

Breaking Change: The layout format has changed significantly from earlier versions:

• Old format: Layout resources defined columns with IDs, tabs were configured separately in the lab resource referencing these column IDs
• New format: Layout resources define columns with tabs inline, no separate tab configuration needed

If migrating from the old format:

layouts.hcl

## OLD (no longer valid)
resource "layout" "two_column" {
  column "terminal" {}

  column "instructions" {
    width = "33"
  }
}

# main.hcl
resource "lab" "example" {
  layout "two_column" {
    reference = resource.layout.two_column

    tab "terminal" {
      panel = "terminal"        # References column ID
      target = resource.terminal.shell
    }

    instructions {
      panel = "instructions"    # References column ID
    }
  }
}

## NEW (current format)
resource "layout" "two_column" {
  column {
    tab "terminal" {
      target = resource.terminal.shell
    }
  }

  column {
    width = "33"

    instructions {}
  }
}

resource "lab" "example" {
  layout = resource.layout.two_column
}

Best Practices

1. Start Simple: Begin with a two-column layout (instructions + terminal)
2. Responsive Design: Consider how your layout will appear on different screen sizes
3. Tab Organization: Group related tabs in the same column/row
4. Active Tabs: Set one tab per column/row as active for better UX
5. Avoid Deep Nesting: Limit nesting to 2-3 levels for maintainability