Terminal User Interface (TUI)

Cbox Init includes a modern, k9s-style terminal user interface for interactive process management. The TUI provides real-time monitoring, process control, and configuration management without leaving your terminal.

Overview

Features:

• 📊 Real-time process status monitoring
• ⌨️ Keyboard-driven interface (Vim-style navigation)
• 🔄 Start, stop, restart, and scale processes interactively
• ➕ Add new processes via interactive wizard
• 📝 View process logs with tail functionality
• 🔌 Dual connectivity (Unix socket + TCP)
• 🔒 Automatic connection fallback and security

Quick Start

# Local connection (auto-detects Unix socket, falls back to TCP)
./cbox-init tui

# Explicit TCP connection
./cbox-init tui --url http://localhost:9180

# Remote connection with authentication
./cbox-init tui --url http://remote-host:9180 --auth your-secret-token

# TLS connection
./cbox-init tui --url https://remote-host:9180 --auth your-secret-token

Connection Modes

The TUI supports two connection modes with intelligent auto-detection:

Unix Socket (Local, Preferred)

Advantages:

• 🔒 Secure: File permissions control access (0600 = owner-only)
• ⚡ Fast: No network stack overhead
• 🎯 Simple: No authentication required (filesystem handles it)

Auto-detected paths (priority order):

1. /var/run/cbox-init.sock
2. /tmp/cbox-init.sock
3. /run/cbox-init.sock

Configuration:

global:
  api_enabled: true
  api_socket: "/var/run/cbox-init.sock"

TCP (Remote, Fallback)

Advantages:

• 🌐 Remote access: Connect from anywhere
• 🔐 Optional TLS: Encrypted connections
• 🛡️ ACL support: IP-based filtering
• 🔑 Authentication: Bearer token auth

Configuration:

global:
  api_enabled: true
  api_port: 9180

  # Optional: Authentication
  api_auth: "your-secret-token"

  # Optional: TLS
  api_tls:
    enabled: true
    cert_file: "/etc/cbox-init/server.crt"
    key_file: "/etc/cbox-init/server.key"

  # Optional: IP ACL
  api_acl:
    allow: ["127.0.0.1", "10.0.0.0/8"]
    deny: []

Auto-Detection Logic

The TUI automatically tries connection methods in this order:

1. ✅ Unix socket (each path in priority order)
   • If socket exists and accessible → Use Unix socket
2. ⏭️ TCP fallback (if no socket found)
   • Falls back to TCP connection

Example:

# TUI tries:
# 1. /var/run/cbox-init.sock → Found! Using Unix socket
# OR
# 1. /var/run/cbox-init.sock → Not found
# 2. /tmp/cbox-init.sock → Not found
# 3. /run/cbox-init.sock → Not found
# 4. http://localhost:9180 → Fallback to TCP

Keyboard Shortcuts

Process List View

Add Process Wizard

Log Viewer

Process Management

Start/Stop/Restart

Interactive control:

1. Navigate to process with ↑/↓ or j/k
2. Press:
   • x to start a stopped process
   • s to stop a running process
   • r to restart a running process
3. Confirmation dialog appears
4. Press Enter to confirm or Esc to cancel

Visual feedback:

• ✅ Success: Green toast notification
• ❌ Error: Red toast notification with error message
• ⏳ In Progress: Status indicator updates in real-time

Scaling Processes

Increase/decrease instances:

1. Navigate to process
2. Press + (scale up) or - (scale down)
3. Scale dialog appears with:
   • Current desired instances
   • Current actual instances
   • Input field for new desired count
4. Enter new value and press Enter
5. Process supervisor adjusts instances automatically

Example:

Process: queue-worker
Current: 3 instances running
Action: Press '+' → Enter '5' → Press Enter
Result: 2 new instances spawned (total: 5)

Add Process Wizard

The interactive wizard guides you through creating a new process configuration.

Wizard Steps

Step 1: Process Name

┌─ Add New Process (1/6) ─────────────────────────┐
│ Process Name                                     │
│ ┌──────────────────────────────────────────────┐ │
│ │ queue-worker-notifications                   │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ Enter unique process identifier (lowercase)     │
└──────────────────────────────────────────────────┘

Step 2: Command

┌─ Add New Process (2/6) ─────────────────────────┐
│ Command                                          │
│ ┌──────────────────────────────────────────────┐ │
│ │ php                                          │ │
│ │ artisan                                      │ │
│ │ queue:work                                   │ │
│ │ --queue=notifications                        │ │
│ │ --tries=3                                    │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ Ctrl+W: Add part  Ctrl+D: Remove selected       │
└──────────────────────────────────────────────────┘

Step 3: Scale (Instances)

┌─ Add New Process (3/6) ─────────────────────────┐
│ Number of Instances                              │
│ ┌──────────────────────────────────────────────┐ │
│ │ 2                                            │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ How many instances to run (1-100)               │
└──────────────────────────────────────────────────┘

Step 4: Restart Policy

┌─ Add New Process (4/6) ─────────────────────────┐
│ Restart Policy                                   │
│ ┌──────────────────────────────────────────────┐ │
│ │ ▶ always                                     │ │
│ │   on-failure                                 │ │
│ │   never                                      │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ↑/↓: Select  Enter: Confirm                     │
└──────────────────────────────────────────────────┘

Step 5: Priority

┌─ Add New Process (5/6) ─────────────────────────┐
│ Startup Priority                                 │
│ ┌──────────────────────────────────────────────┐ │
│ │ 40                                           │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ Lower numbers start first (1-100)               │
└──────────────────────────────────────────────────┘

Step 6: Preview & Confirm

┌─ Add New Process (6/6) ─────────────────────────┐
│ Preview Configuration                            │
│                                                  │
│ Name: queue-worker-notifications                │
│ Command: ["php", "artisan", "queue:work",      │
│           "--queue=notifications", "--tries=3"] │
│ Scale: 2                                         │
│ Restart: always                                  │
│ Priority: 40                                     │
│                                                  │
│ Press Enter to create, Esc to cancel            │
└──────────────────────────────────────────────────┘

Post-Creation

After confirmation:

1. TUI calls API: POST /api/v1/processes with wizard data
2. Process is created in configuration
3. TUI automatically calls: POST /api/v1/config/save to persist
4. Process list refreshes showing new process
5. New process starts automatically (if enabled)

Process Status Display

Status Indicators

NAME              STATUS    INSTANCES  RESTARTS  UPTIME     MEMORY    CPU
php-fpm           ✓ running 2/2        0         2h30m15s   256MB     2.5%
nginx             ✓ running 1/1        0         2h30m10s   64MB      0.8%
horizon           ✓ running 1/1        1         15m30s     128MB     5.2%
queue-default     ✓ running 3/3        0         2h30m05s   384MB     12.1%
queue-emails      ✗ stopped 0/2        5         -          -         -

Status symbols:

• ✓ running - Process is active and healthy
• ✗ stopped - Process is not running
• ⚠ starting - Process is initializing
• ⏸ stopping - Graceful shutdown in progress
• ⚠ unhealthy - Health checks failing

Instance format: actual/desired

• 2/2 - All desired instances running
• 1/2 - Scale drift detected (1 running, 2 desired)
• 0/2 - Process stopped or failed to start

Configuration Requirements

Minimum requirements to use TUI:

global:
  # Enable API server
  api_enabled: true

  # Choose connection method:

  # Option 1: Unix socket (local, recommended)
  api_socket: "/var/run/cbox-init.sock"

  # Option 2: TCP (remote access)
  api_port: 9180

  # Optional: Authentication (TCP only)
  api_auth: "your-secret-token"

Full example with security:

global:
  api_enabled: true
  api_port: 9180
  api_socket: "/var/run/cbox-init.sock"

  # Authentication (TCP only, socket uses file permissions)
  api_auth: "${CBOX_INIT_API_TOKEN}"

  # TLS for remote access
  api_tls:
    enabled: true
    cert_file: "/etc/cbox-init/tls/server.crt"
    key_file: "/etc/cbox-init/tls/server.key"

  # IP ACL for additional security
  api_acl:
    allow: ["127.0.0.1", "10.0.0.0/8"]
    deny: []

Security Considerations

Unix Socket Security

File permissions:

# Recommended: Owner-only access (0600)
chmod 600 /var/run/cbox-init.sock
chown cbox:cbox /var/run/cbox-init.sock

# Verify permissions
ls -la /var/run/cbox-init.sock
# Output: srw------- 1 cbox cbox 0 Nov 24 10:00 cbox-init.sock

Access control:

• Unix socket access controlled by filesystem permissions
• No authentication required (filesystem handles it)
• Recommended for local TUI access on production servers

TCP Security

Best practices:

1. Always use TLS for remote connections
2. Enable authentication with strong tokens
3. Use IP ACL to restrict source IPs
4. Rotate tokens regularly
5. Monitor API access via logs

Production example:

global:
  api_enabled: true
  api_port: 9180
  api_auth: "${CBOX_INIT_API_TOKEN}"  # Load from env

  api_tls:
    enabled: true
    cert_file: "/etc/cbox-init/tls/server.crt"
    key_file: "/etc/cbox-init/tls/server.key"

  api_acl:
    allow: ["10.0.0.0/8"]  # VPN network only
    deny: []

Troubleshooting

TUI Won't Connect

Error: Failed to connect to Cbox Init API

Solutions:

1. Check API is enabled:

   global:
     api_enabled: true
   

2. Verify cbox-init is running:

   ps aux | grep cbox-init
   

3. Check socket exists (local):

   ls -la /var/run/cbox-init.sock
   # Should show: srw------- 1 user user 0 ... cbox-init.sock
   

4. Test TCP connection (remote):

   curl http://localhost:9180/api/v1/health
   # Should return: {"status":"healthy"}
   

5. Check authentication:

   # If api_auth is set, token required
   curl -H "Authorization: Bearer your-token" \
     http://localhost:9180/api/v1/processes
   

Permission Denied on Unix Socket

Error: Permission denied: /var/run/cbox-init.sock

Solutions:

1. Check socket permissions:

   ls -la /var/run/cbox-init.sock
   

2. Add user to socket owner group:

   sudo usermod -a -G cbox $USER
   # Re-login for group changes to take effect
   

3. Run TUI as socket owner:

   sudo -u cbox cbox-init tui
   

Scale/Restart Not Working

Error: Operation failed or no response

Solutions:

1. Check process is enabled:

   processes:
     worker:
       enabled: true  # Must be true
   

2. Verify no config errors:

   cbox-init check-config --strict
   

3. Check API logs:

   # Look for API errors in Cbox logs
   journalctl -u cbox-init -f
   

Examples

Local Development

# Start Cbox Init with TUI-ready config
./cbox-init serve --config dev.yaml

# In another terminal, launch TUI
./cbox-init tui
# Auto-detects socket at /tmp/cbox-init.sock

Remote Production Monitoring

# From local machine, connect to production server
cbox-init tui \
  --url https://prod-server.example.com:9180 \
  --auth "${CBOX_INIT_PROD_TOKEN}"

# Monitor processes, view logs, scale workers as needed

Docker Container Access

# Exec into running container
docker exec -it my-app /bin/sh

# Launch TUI inside container
cbox-init tui
# Uses Unix socket /var/run/cbox-init.sock

Advanced Features

Log Streaming

Real-time log viewing:

1. Navigate to process and press Enter
2. Logs stream in real-time (tail mode)
3. Scroll with ↑/↓ or j/k
4. Jump to top with g, bottom with G
5. Press Esc to return to process list

Features:

• Automatic scrolling (tail -f style)
• Color-coded log levels (ERROR=red, WARN=yellow, etc.)
• Multi-line log reassembly (stack traces)
• Search/filter (coming soon)

Bulk Operations

Scale multiple workers:

1. Scale queue-default from 3→5 (+)
2. Return to list
3. Scale queue-emails from 2→4 (+)
4. All changes persist automatically

Quick restart all:

• Restart each process individually
• Changes apply immediately
• Health checks validate restart success

Integration with API

The TUI uses the Management API under the hood:

See Management API for API documentation.

Next Steps

• Management API - REST API documentation
• Configuration - API configuration reference
• Process Scaling - Scaling strategies and patterns