Virtual Browser

Defined intabs.hcl

The virtual_browser resource adds an embedded virtual browser tab for web-based interactions within a lab. Use it to give users a browser inside the lab UI, pointed at a URL you control, without relying on their local browser.

HCL Syntax

Basic Syntax

resource "virtual_browser" "docs" {
  url = "https://example.com"
}

Fields

Field	Type	Required	Description
url	string	✓	The web address to display in the embedded browser tab
home_url	string	—	The page the home button sends learners to. It does not change where the tab opens — that stays the tab's own URL. Leave it empty and the home button returns learners to that starting page; set it only when the page they should get back to is a different one, such as a dashboard or a login screen they will need again.
browser	string	—	Browser to use for the virtual browser tab Allowedchromium
show_address_bar	bool	—	Shows the page's current address above the tab so learners can see where they are and copy the URL. It is read-only: learners cannot type a new address into it. Defaulttrue
show_zoom_controls	bool	—	Shows zoom out and zoom in buttons with the current zoom percentage above the tab, so learners can make the page easier to read Defaulttrue
show_home_button	bool	—	Shows a home button above the tab that takes learners to the home button URL, or to the tab's own URL when none is set. It is how someone who has navigated away, or landed on a page that will not move, gets back on track. Defaulttrue
show_refresh_button	bool	—	Shows a refresh button above the tab that reloads whatever page the browser is on. A reload is not a return to the start: it re-fetches the live page, wherever learners have got to. Defaulttrue
zoom	number	—	The zoom level the page starts at, as a whole percentage between 50 and 200 (e.g. 125 makes content 25% larger). Learners can still change the zoom while they work, and their choice is kept as they navigate. Default100 Constraintszoom must be at least 50 (percent); zoom must be at most 200 (percent)

Examples

Load an external site

resource "virtual_browser" "console" {
  url = "https://console.example.com"
}

Hide the toolbar

By default, a toolbar above the browser shows a home button, a refresh button, the current URL and a zoom control. Turn all four off to remove the toolbar and give the whole tab to the page.

resource "virtual_browser" "console" {
  url                 = "https://console.example.com"
  show_address_bar    = false
  show_zoom_controls  = false
  show_home_button    = false
  show_refresh_button = false
}

Show only the address bar

resource "virtual_browser" "console" {
  url                 = "https://console.example.com"
  show_zoom_controls  = false
  show_home_button    = false
  show_refresh_button = false
}

Send users back to a starting page

The home button returns to the tab’s own url unless home_url names a different page. Set it only when the page users should get back to is not the one the tab opened on, for example when the tab starts at a login screen.

resource "virtual_browser" "console" {
  url      = "https://console.example.com/login"
  home_url = "https://console.example.com/dashboard"
}

Home and refresh do different things. Home navigates away to a fixed address, while refresh re-fetches the page the browser is currently on, wherever users have got to.

Turn off a single button

Each toggle is independent, and the toolbar stays as long as one of its parts is on. This tab keeps the refresh button, the address bar and the zoom control, but not the home button.

resource "virtual_browser" "console" {
  url              = "https://console.example.com"
  show_home_button = false
}

Set a starting zoom

zoom is a whole percentage from 50 to 200. It sets the level the browser starts at, and users can still change it during the session with the zoom control or the keyboard shortcuts, which keep working when show_zoom_controls is false.

resource "virtual_browser" "console" {
  url  = "https://console.example.com"
  zoom = 125
}

Add the virtual browser to a layout tab to surface it to users.