Configuration Reference

This document provides a reference for BoxMux YAML configuration files.

Table of Contents

File Structure

BoxMux configuration files use YAML format with the following top-level structure:

1
2
3
4

app:
  libs:          # Optional: External script libraries
  variables:     # Optional: Global variables for template substitution
  layouts:       # Required: Layout definitions

Application Configuration

Root Application (app)

Property Type Required Description
libs array[string] No List of external script library files
variables object No Global variables for template substitution
layouts array[Layout] Yes List of layout definitions 
1
2
3
4
5
6
7
8
9
10
11

app:
  libs:
    - lib/utils.sh
    - lib/network.sh
  variables:
    APP_NAME: "BoxMux Dashboard"
    DEFAULT_USER: "admin"
  layouts:
    - id: 'main'
      title: '${APP_NAME}'
      # ... layout configuration

Layout Configuration

Layouts define the overall structure and appearance of your interface.

Layout Properties

Property Type Required Default Description
id string Yes - Unique identifier for the layout
root boolean No false Whether this is the root/main layout
title string No - Layout title (shown in terminal title bar)
bg_color string No "black" Background color
fg_color string No "white" Foreground/text color
title_fg_color string No "white" Title text color
title_bg_color string No "black" Title background color
selected_fg_color string No "black" Selected element text color
selected_bg_color string No "white" Selected element background color
selected_title_fg_color string No "black" Selected title text color
selected_title_bg_color string No "white" Selected title background color
border_color string No "white" Border color
selected_border_color string No "yellow" Selected border color
menu_fg_color string No "white" Menu item text color
menu_bg_color string No "black" Menu item background color
selected_menu_fg_color string No "black" Selected menu item text color
selected_menu_bg_color string No "white" Selected menu item background color
fill_char char No ' ' Character used to fill empty space
children array[Panel] No [] List of child panels

Example Layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14

app:
  layouts:
    - id: 'dashboard'
      root: true
      title: 'My Dashboard'
      bg_color: 'black'
      fg_color: 'white'
      title_fg_color: 'yellow'
      title_bg_color: 'blue'
      selected_bg_color: 'blue'
      border_color: 'green'
      children:
        - id: 'header'
          # ... panel configuration

Panel Configuration

Panels are the building blocks of your interface. They can contain content, menus, or other panels.

Panel Properties

Property Type Required Default Description
id string Yes - Unique identifier for the panel
title string No - Panel title shown in title bar
position Position Yes - Panel position and size
content string No - Static text content
border boolean No true Whether to show border
tab_order string No - Tab navigation order (numeric string)
next_focus_id string No - ID of next panel for custom navigation
refresh_interval number No - Auto-refresh interval in milliseconds
script array[string] No - Shell commands to execute
choices array[Choice] No - Interactive menu choices
redirect_output string No - Panel ID to redirect script output to
append_output boolean No false Whether to append or replace output
on_keypress object No - Keyboard event handlers
variables object No - Panel-local variables for template substitution
overflow_behavior string No "scroll" How to handle overflow: “scroll”, “fill”, “cross_out”, “removed”
scroll boolean No false Enable scrolling for content
min_width number No - Minimum width in characters
min_height number No - Minimum height in characters
max_width number No - Maximum width in characters
max_height number No - Maximum height in characters
children array[Panel] No [] List of child panels

Styling Properties

All layout-level styling properties can be overridden at the panel level:

Property Type Default Description
bg_color string Inherited Background color
fg_color string Inherited Text color
title_fg_color string Inherited Title text color
title_bg_color string Inherited Title background color
selected_bg_color string Inherited Selected background color
selected_fg_color string Inherited Selected text color
selected_title_fg_color string Inherited Selected title text color
selected_title_bg_color string Inherited Selected title background color
border_color string Inherited Border color
selected_border_color string Inherited Selected border color
fill_char char Inherited Fill character
selected_fill_char char Inherited Selected fill character

Position Configuration

Positions define where panels appear on screen using percentage-based coordinates.

Position Properties

Property Type Required Description
x1 string Yes Left edge (percentage or absolute)
y1 string Yes Top edge (percentage or absolute)
x2 string Yes Right edge (percentage or absolute)
y2 string Yes Bottom edge (percentage or absolute)

Position Formats

1
2
3
4
5
6
7
8
9
10
11
12
13

# Percentage-based (recommended)
position:
  x1: 10%      # 10% from left edge
  y1: 20%      # 20% from top edge
  x2: 90%      # 90% from left edge (width = 80%)
  y2: 80%      # 80% from top edge (height = 60%)

# Absolute positioning (not recommended)
position:
  x1: 10       # 10 characters from left
  y1: 5        # 5 lines from top
  x2: 80       # 80 characters from left
  y2: 24       # 24 lines from top

Position Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Full screen
position: { x1: 0%, y1: 0%, x2: 100%, y2: 100% }

# Top half
position: { x1: 0%, y1: 0%, x2: 100%, y2: 50% }

# Bottom half
position: { x1: 0%, y1: 50%, x2: 100%, y2: 100% }

# Left sidebar
position: { x1: 0%, y1: 0%, x2: 20%, y2: 100% }

# Centered box
position: { x1: 25%, y1: 25%, x2: 75%, y2: 75% }

Choice Configuration

Choices create interactive menu items within panels.

Choice Properties

Property Type Required Default Description
id string Yes - Unique identifier for the choice
content string Yes - Text displayed in the menu
script array[string] No - Commands to execute when selected
thread boolean No false Whether to run script in background thread
redirect_output string No - Panel ID to send output to
append_output boolean No false Whether to append or replace output

Choice Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

choices:
  - id: 'deploy'
    content: 'Deploy Application'
    script:
      - echo 'Starting deployment...'
      - ./deploy.sh
      - echo 'Deployment complete!'
    redirect_output: 'status'
    append_output: true
    
  - id: 'status'
    content: 'Check Status'
    script:
      - systemctl status myapp
    redirect_output: 'output'

Color Reference

BoxMux supports the following color names:

Basic Colors

Bright Colors

Special Colors

Color Usage Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Basic usage
bg_color: 'black'
fg_color: 'white'

# Bright colors for emphasis
title_fg_color: 'bright_yellow'
selected_bg_color: 'bright_blue'

# Mixed color scheme
bg_color: 'black'
fg_color: 'green'
title_fg_color: 'bright_white'
title_bg_color: 'blue'
border_color: 'cyan'

Script Configuration

Scripts define commands that panels can execute.

Script Properties

Scripts are defined as arrays of shell commands:

1
2
3
4

script:
  - echo 'Hello World'
  - date
  - ls -la

Script Features

Script Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Simple commands
script:
  - echo 'Current time:'
  - date

# Multi-line command
script:
  - >
    echo "System info:"
    uname -a
    df -h

# Complex pipeline
script:
  - ps aux | grep -v grep | grep nginx | wc -l

# Background script
script:
  - tail -f /var/log/syslog
thread: true

Features

Keyboard Event Handlers

Define custom keyboard shortcuts:

1
2
3
4
5
6
7
8

on_keypress:
  r:                    # Press 'r' key
    - echo 'Refreshing...'
    - date
  q:                    # Press 'q' key
    - exit
  'ctrl+c':            # Ctrl+C combination
    - echo 'Interrupted'

Title Positioning

Control where titles appear:

1
2
3

title_position: 'start'    # Left-aligned
title_position: 'center'   # Centered
title_position: 'end'      # Right-aligned

Anchoring

Control how panels are anchored:

1
2
3
4
5

anchor: 'TopLeft'      # Default
anchor: 'TopRight'
anchor: 'BottomLeft'
anchor: 'BottomRight'
anchor: 'Center'

Overflow Behavior

Control how content overflow is handled:

1
2
3
4

overflow_behavior: 'scroll'      # Default: enable scrolling
overflow_behavior: 'fill'        # Fill with solid block
overflow_behavior: 'cross_out'   # Cross out with X's
overflow_behavior: 'removed'     # Hide the panel

Variable System

BoxMux includes hierarchical variable substitution for dynamic configuration, template-driven interfaces, and environment-specific deployments.

Variable Syntax

Variables use the following patterns:

Variable Precedence (Hierarchical Resolution)

Variables are resolved in strict hierarchical order:

  1. Panel-specific variables (highest precedence, most granular)
  2. Parent panel variables (inherited through panel hierarchy)
  3. Layout-level variables (layout scope)
  4. Application-global variables (app-wide scope)
  5. Environment variables (system fallback)
  6. Default values (built-in fallbacks, lowest precedence)

This hierarchical approach allows child panels to override parent settings while providing sensible fallbacks.

Variable Declaration

Application-level Variables

Define global variables that apply across all layouts:

1
2
3
4
5
6

app:
  variables:
    APP_NAME: "Production Dashboard"
    SERVER_HOST: "prod-server.company.com"
    LOG_LEVEL: "info"
    DEFAULT_USER: "admin"

Panel-level Variables

Define panel-specific variables that override global settings:

1
2
3
4
5
6
7
8
9

- id: 'web_server_panel'
  variables:
    SERVICE_NAME: "nginx"
    PORT: "80"
    CONFIG_PATH: "/etc/nginx"
  title: '${SERVICE_NAME} Server Status'
  script:
    - echo "Checking ${SERVICE_NAME} on port ${PORT}"
    - systemctl status ${SERVICE_NAME}

Variable Inheritance

Child panels automatically inherit variables from their parents, creating a natural configuration hierarchy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

app:
  variables:
    ENVIRONMENT: "production"
    
  layouts:
    - id: 'monitoring'
      children:
        - id: 'parent_panel'
          variables:
            SERVICE_GROUP: "web-services"
          children:
            - id: 'child_panel'
              variables:
                SERVICE_NAME: "api-gateway"
              title: '${SERVICE_NAME} in ${SERVICE_GROUP} (${ENVIRONMENT})'
              # Resolves to: "api-gateway in web-services (production)"

Variable Fields

Variables work in all configuration fields:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

- id: 'dynamic_panel'
  variables:
    SERVICE: "database"
    LOG_FILE: "/var/log/postgresql.log"
  title: '${SERVICE} Monitor'           # Title substitution
  content: 'Monitoring ${SERVICE}'      # Content substitution
  script:                               # Script substitution
    - echo "Starting ${SERVICE} check"
    - tail -f ${LOG_FILE}
  redirect_output: '${SERVICE}_output'  # Redirect target substitution
  choices:
    - id: 'restart'
      content: 'Restart ${SERVICE}'     # Choice content substitution
      script:
        - systemctl restart ${SERVICE}  # Choice script substitution

Advanced Examples

Environment-specific Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

app:
  variables:
    ENVIRONMENT: "staging"
    DB_HOST: "staging-db.internal"
    API_URL: "https://api-staging.company.com"
    
  layouts:
    - id: 'deployment_dashboard'
      title: 'Deployment Dashboard - ${ENVIRONMENT}'
      children:
        - id: 'database_panel'
          variables:
            SERVICE_NAME: "PostgreSQL"
          title: '${SERVICE_NAME} Status'
          script:
            - echo "Connecting to ${DB_HOST}..."
            - pg_isready -h ${DB_HOST}
            
        - id: 'api_panel'
          variables:
            SERVICE_NAME: "API Gateway"
          title: '${SERVICE_NAME} Health'
          script:
            - curl -s ${API_URL}/health | jq .

Multi-service Monitoring

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

app:
  variables:
    DEFAULT_USER: "monitor"
    SSH_KEY: "~/.ssh/monitoring_key"
    
  layouts:
    - id: 'infrastructure'
      children:
        - id: 'web_servers'
          variables:
            SERVER_TYPE: "web"
          children:
            - id: 'web1'
              variables:
                HOST: "web1.company.com"
                SERVICE: "nginx"
              title: '${SERVICE}@${HOST}'
              script:
                - ssh -i ${SSH_KEY} ${USER:${DEFAULT_USER}}@${HOST} 'systemctl status ${SERVICE}'
                
            - id: 'web2'
              variables:
                HOST: "web2.company.com" 
                SERVICE: "apache2"
              title: '${SERVICE}@${HOST}'
              script:
                - ssh -i ${SSH_KEY} ${USER:${DEFAULT_USER}}@${HOST} 'systemctl status ${SERVICE}'

Template-driven Deployment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

app:
  variables:
    DEPLOYMENT_ENV: "production"
    NAMESPACE: "default"
    
  layouts:
    - id: 'kubernetes_deploy'
      title: 'K8s Deployment - ${DEPLOYMENT_ENV}'
      children:
        - id: 'frontend_deploy'
          variables:
            APP_NAME: "frontend"
            REPLICAS: "3"
            IMAGE_TAG: "v1.2.0"
          title: 'Deploy ${APP_NAME}'
          script:
            - echo "Deploying ${APP_NAME} to ${DEPLOYMENT_ENV}"
            - kubectl set image deployment/${APP_NAME} ${APP_NAME}=${APP_NAME}:${IMAGE_TAG} -n ${NAMESPACE}
            - kubectl scale deployment/${APP_NAME} --replicas=${REPLICAS} -n ${NAMESPACE}

Environment Variable Integration

Seamlessly integrate with existing environment variables:

1
2
3
4
5
6
7
8
9
10
11
12

# These variables will use environment values if set,
# otherwise fall back to YAML-defined defaults
app:
  variables:
    LOG_LEVEL: "info"  # Overridden by $LOG_LEVEL if set
    
  layouts:
    - id: 'app_panel'
      script:
        - echo "Running with LOG_LEVEL=${LOG_LEVEL}"
        - echo "User: ${USER:unknown}"          # Uses $USER or "unknown"
        - echo "Home: ${HOME:/tmp}"             # Uses $HOME or "/tmp"

Error Handling

The variable system provides clear error messages for common issues:

Best Practices

  1. Use hierarchical variables for environment-specific configurations
  2. Provide meaningful defaults to prevent empty substitutions
  3. Group related variables at appropriate levels (app/layout/panel)
  4. Use descriptive variable names that indicate their scope and purpose
  5. Leverage inheritance to reduce configuration duplication

Example Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

app:
  variables:
    APP_NAME: "My Dashboard"
    REFRESH_RATE: "1000"
  layouts:
    - id: 'main'
      title: '${APP_NAME} v${VERSION:1.0}'
      children:
        - id: 'panel1'
          variables:
            LOCAL_VAR: "panel-specific"
          script:
            - echo "User: ${USER:unknown}"
            - echo "App: ${APP_NAME}"
            - echo "Local: ${LOCAL_VAR}"
            - echo "Home: $HOME"

For detailed documentation, see Variable System Guide.

Validation Rules

Required Fields

ID Naming Rules

Position Validation

Color Validation

Examples

Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

app:
  libs:
    - lib/system.sh
    - lib/network.sh
  layouts:
    - id: 'main'
      root: true
      title: 'System Dashboard'
      bg_color: 'black'
      fg_color: 'white'
      title_fg_color: 'bright_yellow'
      title_bg_color: 'blue'
      selected_bg_color: 'bright_blue'
      border_color: 'green'
      children:
        - id: 'header'
          title: 'System Status'
          position:
            x1: 0%
            y1: 0%
            x2: 100%
            y2: 15%
          content: 'System Dashboard v1.0'
          border: true
          
        - id: 'sidebar'
          title: 'Navigation'
          position:
            x1: 0%
            y1: 15%
            x2: 25%
            y2: 85%
          tab_order: '1'
          choices:
            - id: 'cpu'
              content: 'CPU Usage'
              script:
                - top -l 1 | grep "CPU usage"
              redirect_output: 'main_content'
            - id: 'memory'
              content: 'Memory Usage'
              script:
                - top -l 1 | grep "PhysMem"
              redirect_output: 'main_content'
            - id: 'disk'
              content: 'Disk Usage'
              script:
                - df -h
              redirect_output: 'main_content'
              
        - id: 'main_content'
          title: 'Output'
          position:
            x1: 25%
            y1: 15%
            x2: 100%
            y2: 85%
          content: 'Select an option from the menu'
          scroll: true
          
        - id: 'footer'
          title: 'Status'
          position:
            x1: 0%
            y1: 85%
            x2: 100%
            y2: 100%
          refresh_interval: 1000
          script:
            - date
          border: false

Minimal Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12

app:
  layouts:
    - id: 'simple'
      root: true
      children:
        - id: 'content'
          position:
            x1: 10%
            y1: 10%
            x2: 90%
            y2: 90%
          content: 'Hello, World!'

Best Practices

  1. Use meaningful IDs: Choose descriptive names for layouts, panels, and choices
  2. Plan your layout: Sketch your interface before writing YAML
  3. Test incrementally: Start with simple configurations and add complexity
  4. Use consistent styling: Define colors at the layout level when possible
  5. Optimize refresh intervals: Balance real-time updates with performance
  6. Handle errors gracefully: Consider what happens when scripts fail
  7. Document your configuration: Use YAML comments to explain complex sections

Common Patterns

Dashboard Layout

1
2
3
4
5
6
7
8
9
10

# Header + Sidebar + Main + Footer
children:
  - id: 'header'
    position: { x1: 0%, y1: 0%, x2: 100%, y2: 10% }
  - id: 'sidebar'
    position: { x1: 0%, y1: 10%, x2: 20%, y2: 90% }
  - id: 'main'
    position: { x1: 20%, y1: 10%, x2: 100%, y2: 90% }
  - id: 'footer'
    position: { x1: 0%, y1: 90%, x2: 100%, y2: 100% }

Grid Layout

1
2
3
4
5
6
7
8
9
10

# 2x2 grid
children:
  - id: 'top_left'
    position: { x1: 0%, y1: 0%, x2: 50%, y2: 50% }
  - id: 'top_right'
    position: { x1: 50%, y1: 0%, x2: 100%, y2: 50% }
  - id: 'bottom_left'
    position: { x1: 0%, y1: 50%, x2: 50%, y2: 100% }
  - id: 'bottom_right'
    position: { x1: 50%, y1: 50%, x2: 100%, y2: 100% }

Modal/Dialog Pattern

1
2
3
4
5
6

# Centered modal
- id: 'modal'
  position: { x1: 25%, y1: 25%, x2: 75%, y2: 75% }
  bg_color: 'white'
  fg_color: 'black'
  border_color: 'red'

For more examples and tutorials, see the Examples document.