PTY (Pseudo-Terminal) Features

Interactive terminal emulation in BoxMux boxes

PTY features enable running interactive terminal programs within BoxMux boxes, providing keyboard interaction, ANSI processing, and process management.

Table of Contents

Overview

PTY (Pseudo-Terminal) features allow you to run interactive terminal applications like vim, htop, ssh, less, nano, and database shells within BoxMux boxes. This provides terminal multiplexing with organized box layouts.

Key Benefits

Basic PTY Configuration

Enable PTY for any box by adding pty: true:

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

app:
  layouts:
    - id: 'main'
      children:
        - id: 'interactive_box'
          title: 'Interactive Terminal ⚡'
          pty: true
          script:
            - htop
          position:
            x1: 0%
            y1: 0%
            x2: 100%
            y2: 100%

PTY vs Regular Execution

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

# Regular script execution (non-interactive)
- id: 'regular_box'
  title: 'System Info'
  script:
    - ps aux | head -10
    - df -h
  refresh_interval: 5000

# PTY execution (interactive)
- id: 'pty_box'
  title: 'Interactive Top ⚡'
  pty: true
  script:
    - htop
  # No refresh_interval needed - PTY runs continuously

Interactive Applications

System Monitoring

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

- id: 'htop_monitor'
  title: 'System Monitor ⚡'
  pty: true
  script:
    - htop
  position:
    x1: 0%
    y1: 0%
    x2: 50%
    y2: 50%

- id: 'iotop_monitor'
  title: 'IO Monitor ⚡'
  pty: true
  script:
    - sudo iotop
  position:
    x1: 50%
    y1: 0%
    x2: 100%
    y2: 50%

Text Editors

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

- id: 'vim_editor'
  title: 'Text Editor ⚡'
  pty: true
  script:
    - vim /path/to/config.yaml
  position:
    x1: 0%
    y1: 0%
    x2: 100%
    y2: 70%

- id: 'nano_editor'
  title: 'Simple Editor ⚡'
  pty: true
  script:
    - nano /etc/hosts

Remote Connections

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

- id: 'ssh_session'
  title: 'Production Server ⚡'
  pty: true
  script:
    - ssh user@production-server.com
  position:
    x1: 0%
    y1: 0%
    x2: 50%
    y2: 100%

- id: 'database_shell'
  title: 'Database Console ⚡'
  pty: true
  script:
    - psql -h localhost -U postgres -d myapp
  position:
    x1: 50%
    y1: 0%
    x2: 100%
    y2: 100%

File Navigation

1
2
3
4
5
6
7

- id: 'file_manager'
  title: 'File Manager ⚡'
  pty: true
  script:
    - ranger
    # or: mc (midnight commander)
    # or: nnn

PTY Process Management

Lifecycle Control

PTY processes have full lifecycle management:

Process Status

PTY boxes show process information in their titles:

1
2
3
4

Interactive Top ⚡ [PID: 12345, Running]
SSH Session ⚡ [PID: 12346, Connected]  
Text Editor ⚡ [Process Stopped]
Database Shell ⚡ [PID: 12347, Error]

Process Actions

Available process management actions:

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

# In choice menus for PTY control
- id: 'pty_controls'
  title: 'PTY Controls'
  choices:
    - id: 'kill_htop'
      content: 'Kill htop process'
      script:
        - echo '{"Command": {"action": "kill_pty", "box_id": "htop_monitor"}}' | nc -U /tmp/boxmux.sock
    
    - id: 'restart_ssh'
      content: 'Restart SSH session'
      script:
        - echo '{"Command": {"action": "restart_pty", "box_id": "ssh_session"}}' | nc -U /tmp/boxmux.sock

Input and Navigation

Keyboard Input Routing

When a PTY box is focused, all keyboard input is routed directly to the running process:

1
2
3
4
5

Arrow Keys:     ↑ ↓ ← →
Function Keys:  F1 F2 F3 ... F24
Navigation:     Home End PageUp PageDown
Editing:        Insert Delete Backspace
Modifiers:      Ctrl+C Ctrl+Z Ctrl+D etc.

Focus Management

Switch between PTY and regular boxes:

Scrollback Navigation

PTY boxes maintain scrollback history:

Visual Indicators

Box Title Indicators

PTY boxes display special visual indicators:

1
2
3
4

Regular Box:      "System Info"
PTY Box:          "Interactive Top ⚡" 
PTY with Process:   "SSH Session ⚡ [PID: 12345, Running]"
PTY Error State:    "Failed Process ⚡ [Process Stopped]"

Border Colors

PTY boxes use distinct border colors:

Status Information

Process status appears in box titles:

Socket Control

Remote PTY Management

Control PTY processes via Unix socket:

1
2
3
4
5
6
7
8
9
10
11

# Kill PTY process
echo '{"Command": {"action": "kill_pty", "box_id": "htop_box"}}' | nc -U /tmp/boxmux.sock

# Restart PTY process  
echo '{"Command": {"action": "restart_pty", "box_id": "ssh_session"}}' | nc -U /tmp/boxmux.sock

# Query PTY status
echo '{"Command": {"action": "pty_status", "box_id": "vim_box"}}' | nc -U /tmp/boxmux.sock

# Send input to PTY (for automation)
echo '{"Command": {"action": "pty_input", "box_id": "database", "input": "SELECT * FROM users LIMIT 5;\n"}}' | nc -U /tmp/boxmux.sock

Batch Operations

1
2
3
4
5
6
7
8

# Kill all PTY processes
for box in htop_box ssh_session vim_editor; do
  echo '{"Command": {"action": "kill_pty", "box_id": "'$box'"}}' | nc -U /tmp/boxmux.sock
done

# Restart development environment
echo '{"Command": {"action": "restart_pty", "box_id": "vim_editor"}}' | nc -U /tmp/boxmux.sock
echo '{"Command": {"action": "restart_pty", "box_id": "test_runner"}}' | nc -U /tmp/boxmux.sock

Error Handling

Automatic Fallback

When PTY fails, BoxMux automatically falls back to regular execution:

1
2
3
4
5

- id: 'robust_box'
  title: 'System Status'
  pty: true  # Try PTY first
  script:
    - htop  # Interactive if PTY works, static output if PTY fails

Failure Tracking

BoxMux tracks PTY failures and avoids repeated attempts:

Error States

PTY boxes can be in various error states:

1
2
3
4
5

# Error state indicators in titles
"Process Name ⚡ [Process Stopped]"      # Process exited
"Process Name ⚡ [PTY Failed]"           # PTY allocation failed  
"Process Name ⚡ [Connection Lost]"      # SSH/network failure
"Process Name ⚡ [Permission Denied]"    # Insufficient permissions

Error Recovery

Manual recovery options:

Best Practices

Performance Considerations

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

# Good: Specific PTY processes
- id: 'htop_box'
  pty: true
  script:
    - htop

# Avoid: Heavy output in PTY
- id: 'log_box'  
  pty: false  # Use regular execution for high-volume logs
  script:
    - tail -f /var/log/messages
  auto_scroll_bottom: true

Resource Management

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

# Limit concurrent PTY processes
app:
  layouts:
    - id: 'development'
      children:
        # Core interactive tools (keep PTY)
        - id: 'vim_editor'
          pty: true
          script: [vim]
        
        - id: 'htop_monitor'  
          pty: true
          script: [htop]
          
        # Background processes (regular execution)
        - id: 'build_output'
          pty: false
          streaming: true
          script: [./watch-build.sh]

Security Considerations

1
2
3
4
5
6
7

# Be careful with PTY and sensitive operations
- id: 'secure_session'
  title: 'Admin Console ⚡'
  pty: true
  script:
    - ssh -o ServerAliveInterval=60 admin@secure-server
  # Consider: timeout, logging, access controls

Layout Design

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

# Organize PTY boxes logically
app:
  layouts:
    - id: 'development'
      title: 'Development Environment'
      children:
        # Main editor (large space)
        - id: 'editor'
          title: 'Code Editor ⚡'
          pty: true
          script: [vim]
          position: {x1: 0%, y1: 0%, x2: 70%, y2: 70%}
          
        # Monitoring (side box)  
        - id: 'system'
          title: 'System Monitor ⚡'
          pty: true
          script: [htop]
          position: {x1: 70%, y1: 0%, x2: 100%, y2: 50%}
          
        # Terminal (bottom)
        - id: 'shell'
          title: 'Shell ⚡'
          pty: true
          script: [bash]
          position: {x1: 0%, y1: 70%, x2: 100%, y2: 100%}

Troubleshooting

Common PTY issues and solutions:

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

# Issue: PTY not starting
# Solution: Check permissions and binary paths
- id: 'debug_box'
  pty: true
  script:
    - /usr/bin/htop  # Use full path
    
# Issue: Input not working
# Solution: Ensure box is focused and check key bindings

# Issue: Display corruption
# Solution: Use ANSI processing and proper terminal size
- id: 'clean_display'
  pty: true
  script:
    - TERM=xterm-256color htop

PTY features provide powerful terminal multiplexing capabilities within BoxMux’s organized box system, enabling complex interactive workflows with proper process management and visual organization.