Terminal

Defined intabs.hcl

The terminal resource provides an interactive shell session tab that users can use to execute commands in a container or VM. It creates a fully functional terminal emulator in the browser that connects to the target resource.

Use Cases

As a lab author, you can use terminal resources to provide command-line access:

• Command-Line Access: Give users shell access to servers, containers, and VMs for configuration and management tasks
• Custom Shell Environments: Create terminals with specific prompts, aliases, or pre-configured tools for specialized workflows
• Cloud VM Access: SSH into cloud VM instances for infrastructure management and configuration

Terminals are essential for hands-on learning where users need direct command-line interaction with systems.

HCL Syntax

Basic Syntax

resource "terminal" "name" {
  target = resource.container.ubuntu
}

Full Syntax

resource "terminal" "name" {
  target            = resource.container.ubuntu
  shell             = "/bin/bash"
  user              = "root"
  group             = "root"
  working_directory = "/home/user"
  command           = ["tmux", "new-session"]
}

Fields

Field	Type	Required	Description
target	referencecontainer, vm	✓	Select the sandbox component where this terminal connects. The terminal opens a shell session in that environment.
shell	string	—	Optional. Specify the shell to use (for example, bash or sh). Leave empty to use the system's default shell. Default/bin/sh
user	string	—	Optional. Define which user the terminal session runs as inside the sandbox. This helps control permissions and environment access.
group	string	—	Optional. Assign a group for the user session if specific group permissions are needed.
working_directory	string	—	Optional. Set the directory where the terminal opens when launched.
command	list(string)	—	Optional. Define a command to run automatically when the terminal starts, such as initializing a script or printing a welcome message.
prompt	string	—	Custom shell prompt string
theme	string	—	Color theme for the terminal Alloweddark light monokai solarized

Examples

Basic Terminal

resource "terminal" "main" {
  target = resource.container.ubuntu
}

Terminal Targeting a VM

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

Note

When the terminal target is a VM, the session is proxied through the in-VM agent over the sandbox network. The shell, user, group, and working_directory fields are interpreted by the VM’s operating system, so the shell binary must exist inside the VM (for example /bin/bash) and the user and group must exist in the VM.

Terminal with Bash Shell

resource "terminal" "bash_terminal" {
  target = resource.container.devbox
  shell  = "/bin/bash"
  user   = "developer"
  group  = "developer"
  working_directory = "/home/developer"
}

Terminal with Initial Command

resource "terminal" "monitoring" {
  target  = resource.container.monitor
  command = ["htop"]
}

Multiple Terminals in Layout

resource "layout" "multi_terminal" {
  column {
    width = "30"
    instructions {}
  }

  column {
    width = "35"

    tab "server" {
      target = resource.terminal.server
      title  = "Server"
      active = true
    }

    tab "client" {
      target = resource.terminal.client
      title  = "Client"
    }
  }

  column {
    width = "35"

    tab "logs" {
      target = resource.terminal.logs
      title  = "Logs"
    }
  }
}

Terminal with Tmux Session

resource "terminal" "tmux" {
  target            = resource.container.workspace
  shell             = "/bin/bash"
  working_directory = "/workspace"
  command           = ["tmux", "new-session", "-s", "main"]
}

Terminal for Database CLI

resource "terminal" "postgres_cli" {
  target  = resource.container.postgres
  user    = "postgres"
  group   = "postgres"
  command = ["psql", "-d", "mydb"]
}

Best Practices

1. Shell Selection: Use /bin/bash for better interactive features, fallback to /bin/sh for minimal containers or VMs
2. User Configuration: Run terminals as non-root users when possible for security
3. Working Directory: Set appropriate starting directories for the lab context
4. Multiple Terminals: Use descriptive resource names when creating multiple terminals
5. Initial Commands: Use the command field for specialized tools (e.g. database CLIs, monitoring tools)

Common Issues

1. Shell Not Found: Terminal fails to start with “shell not found” error

   • Verify the shell exists in the target resource
   • Use /bin/sh as a fallback for minimal images

2. Permission Denied: Terminal cannot access certain directories or files

   • Check user/group permissions match the target resource’s file ownership
   • Ensure the working directory is accessible by the specified user

3. Target Type Error: “target can only be of the following types: container, vm”

   • For Kubernetes clusters, create a container with kubectl configured
   • Use a jump host or bastion container for cluster access

Kubernetes Cluster Access

To provide terminal access to a Kubernetes cluster:

## Container with kubectl configured
resource "container" "kubectl" {
  image {
    name = "bitnami/kubectl:latest"
  }

  volume {
    source      = resource.kubernetes_cluster.k8s.kubeconfig_path
    destination = "/root/.kube/config"
    type        = "bind"
  }
}

# Terminal accessing the kubectl container
resource "terminal" "k8s_terminal" {
  target            = resource.container.kubectl
  working_directory = "/root"
}