Basic Usage - Undying Terminal

Daily Workflow

Starting Your Day

Start Server (if not running as service)

./undying-terminal-server.exe

Leave this running in a dedicated terminal window.

Start Terminal Session

echo "XXX" | ./undying-terminal-terminal.exe

First run only: Save the client ID and passkey shown.

Connect Client

./undying-terminal.exe `
  --connect 127.0.0.1 2022 <CLIENT_ID> `
  --key <PASSKEY> `
  --noexit

Tip: Save this command in a script for quick access.

Ending Your Day

Simply close the client terminal. Your session stays alive! Tomorrow:

Server still running
Terminal still active
Just reconnect the client

Common Commands

Interactive Session

# Standard interactive connection
./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  --noexit

Use this for:

Day-to-day terminal work
Long-running processes
Remote development

One-Shot Commands

# Execute single command and exit
./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  -c "dir`r`n"

Include `r`n (carriage return + newline) for cmd.exe to execute the command.

Built-in UI Mode

Launch the interactive text-based UI for managing multiple sessions:

# Start the built-in UI
./undying-terminal.exe --ui

UI Commands:

add <name> <host> <port> <client_id> <passkey>    # Create a profile
set-tunnel <name> <spec>                          # Configure port forwarding
set-flag <name> <noexit|tunnel-only|predictive-echo> <on|off>  # Set options
start <name>                                       # Launch a session
stop <name>                                        # Stop a running session
remove <name>                                      # Delete a profile
list                                               # Show all profiles
help                                               # Show commands
quit                                               # Exit UI

Example Session:

ut-ui> add dev 127.0.0.1 2022 abc123 mypasskey
Profile 'dev' added

ut-ui> set-flag dev predictive-echo on
Flag 'predictive-echo' set to 'on' for profile 'dev'

ut-ui> start dev
started 'dev' (pid=12345)

ut-ui> list
- dev host=127.0.0.1 port=2022 running=yes tunnel-only=off predictive-echo=on

ut-ui> quit

SSH Bootstrap (Remote Servers)

# Connect to remote server, start terminal, connect directly
./undying-terminal.exe --ssh user@remote-server.com -l username

With Tmux Integration:

# Auto-attach to tmux session (creates if doesn't exist)
./undying-terminal.exe --ssh user@remote-server.com -l username --tmux --tmux-session mysession

This:

SSHs to remote server
Starts undying-terminal-terminal there (optionally inside tmux)
Extracts credentials
Switches to direct TCP connection
Keeps session alive forever

Practical Scenarios

Scenario 1: Development Workflow

# Terminal 1: Server
./undying-terminal-server.exe

# Terminal 2: Dev session
echo "dev-session" | ./undying-terminal-terminal.exe
# Note client_id and passkey

# Terminal 3: Connect with tunnels
./undying-terminal.exe `
  --connect 127.0.0.1 2022 <CLIENT_ID> `
  --key <PASSKEY> `
  -t 5432:db-server:5432 `     # Database
  -t 6379:redis-server:6379 `  # Redis
  -t 3000:api-server:3000 `    # API
  --noexit

Scenario 2: Long-Running Builds

# Start build in persistent session
./undying-terminal.exe --connect ... --noexit

# In session:
cmake --build . --config Release
# This takes 2 hours...

# Network drops? No problem - session continues
# Reconnect and see build progress:
./undying-terminal.exe --connect ... --noexit

Scenario 3: Remote Administration

# From workstation, bootstrap to server
./undying-terminal.exe --ssh admin@prod-server.com -l admin

# Session started!
# Now you have persistent access to prod-server

Scenario 4: Unstable Network Environments

# Working from coffee shop with flaky WiFi
./undying-terminal.exe `
  --ssh dev-server.com -l developer

# In session, start long task:
python train-model.py  # Takes 6 hours

# WiFi drops? No problem
# Automatic reconnect every 100ms-2000ms

# Model training continues uninterrupted

Session Management

Built-in UI Multi-Session (v1.1.0+)

The easiest way to manage multiple sessions is with the built-in UI:

# Launch the UI
./undying-terminal.exe --ui

# Create profiles for different environments
ut-ui> add dev localhost 2022 dev-id dev-key
ut-ui> add prod prod-server.com 2022 prod-id prod-key
ut-ui> add staging staging-server.com 2022 staging-id staging-key

# Start any session
ut-ui> start dev

# Switch between sessions by stopping one and starting another
ut-ui> stop dev
ut-ui> start prod

Traditional Multiple Sessions

Run multiple independent sessions manually:

# Terminal 1
echo "dev" | ./undying-terminal-terminal.exe
# client_id: dev-001, passkey: abc123

# Connect to dev session
./undying-terminal.exe --connect 127.0.0.1 2022 dev-001 --key abc123 --noexit

Session Discovery

Track active sessions:

# Keep a sessions.txt file
@"
Dev Session:
  client_id: abc123def456
  passkey: 1234567890abcdef
  purpose: Development work
  
Prod Session:
  client_id: xyz789ghi012
  passkey: fedcba0987654321
  purpose: Production monitoring
"@ | Out-File sessions.txt

Keyboard Shortcuts

Shortcut	Action
`Ctrl+C`	Interrupt current command (sent to shell)
`Ctrl+D`	Send EOF (may exit shell)
`Ctrl+Z`	Suspend (Windows behavior)

Exiting the shell (e.g., exit or Ctrl+D) will terminate the terminal process. This ends the session! Use client disconnect instead.

Advanced Features

Predictive Echo (v1.1.0+)

Enable local echo prediction for high-latency connections:

# Direct connection with predictive echo
./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  --predictive-echo `
  --noexit

# SSH bootstrap with predictive echo
./undying-terminal.exe --ssh user@remote --predictive-echo

When to use:

Connections with >100ms latency
Satellite or cellular networks
International connections

How it works:

Characters appear instantly (local echo)
Server output reconciles with local echo
No duplicate characters visible

Tunnel-Only Mode (v1.1.0+)

Run port forwarding without terminal overhead:

# Forward ports without interactive shell
./undying-terminal.exe `
  --connect <HOST> <PORT> <CLIENT_ID> `
  --key <PASSKEY> `
  -t 5432:db-server:5432 `
  -t 6379:redis:6379 `
  --tunnel-only

Use cases:

Database tunneling
API proxy connections
Secure access to internal services
CI/CD pipeline integration

IPv6 Support (v1.1.0+)

Connect to IPv6 hosts:

# IPv6 address
./undying-terminal.exe --connect 2001:db8::1 2022 <ID> --key <KEY>

# IPv6 with SSH bootstrap
./undying-terminal.exe --ssh user@[2001:db8::1] -l username

# IPv6 tunnels
./undying-terminal.exe `
  --connect <HOST> <PORT> <ID> `
  --key <KEY> `
  -t "[::1]:8080:[2001:db8::1]:80"

Disconnecting vs. Exiting

Client Disconnect (Safe)

# Simply close the client terminal window
# OR press Ctrl+C in client terminal

Result:

Session stays alive
Terminal keeps running
Can reconnect anytime

Shell Exit (Dangerous)

# In the session:
exit

# OR
Ctrl+D

Result:

Shell terminates
Terminal process exits
Session ends
Must restart terminal

Best practice: Always disconnect the client, never exit the shell.

Scripting and Automation

Connection Script

Save frequently-used connections:

# connect-dev.ps1
$clientId = "abc123def456"
$passkey = "1234567890abcdef"

./undying-terminal.exe `
  --connect 127.0.0.1 2022 $clientId `
  --key $passkey `
  -t 5432:db:5432 `
  -t 6379:redis:6379 `
  --noexit

Usage:

.\connect-dev.ps1    # Instant connection

Automated Commands

# run-backup.ps1
$clientId = "server-backup"
$passkey = "backup-key"

./undying-terminal.exe `
  --connect backup-server.com 2022 $clientId `
  --key $passkey `
  -c "./backup.ps1`r`n"

Monitoring and Logging

Client-Side Logging

Enable debug logging:

# Handshake debugging
$env:UT_DEBUG_HANDSHAKE = 1
./undying-terminal.exe --connect ...

# Server-side verbose logging
# In ut.cfg:
verbose=true

Check Connection Status

# While connected, check server status
netstat -ano | findstr :2022

# Check if terminal is running
tasklist | findstr undying-terminal-terminal

Tips and Tricks

Reconnect Faster

When you know you’ll reconnect soon:

# Keep client_id and passkey in environment
$env:UT_CLIENT_ID = "abc123"
$env:UT_PASSKEY = "mykey"

# Quick reconnect
./undying-terminal.exe `
  --connect 127.0.0.1 2022 $env:UT_CLIENT_ID `
  --key $env:UT_PASSKEY `
  --noexit

Run Server as Background Job

# PowerShell background job
Start-Job -ScriptBlock {
  Set-Location "C:\Program Files\UndyingTerminal"
  .\undying-terminal-server.exe
}

# Check status
Get-Job

# Stop
Get-Job | Stop-Job

Better: Install as Windows service for production.

Test Session Recovery

# 1. Start long-running command
ping -t 8.8.8.8

# 2. Disconnect client (Ctrl+C or close window)

# 3. Simulate delay
Start-Sleep -Seconds 10

# 4. Reconnect
./undying-terminal.exe --connect ... --noexit

# 5. Verify: ping output continues, recent history replayed

Reduce Keepalive Traffic

For bandwidth-constrained networks:

// In source: Keepalive.cpp
// Change interval from 5s to 30s
constexpr auto kKeepaliveInterval = std::chrono::seconds(30);

Rebuild and use custom binary.

Next Steps

Port Forwarding

Tunnel local and remote ports

SSH Bootstrap

Start remote sessions via SSH

Configuration

Customize server behavior

Troubleshooting

Solve common problems

Getting Started

Core Concepts

Configuration

Troubleshooting

Development

​Daily Workflow

​Starting Your Day

​Ending Your Day

​Common Commands

​Interactive Session

​One-Shot Commands

​Built-in UI Mode

​SSH Bootstrap (Remote Servers)

​Practical Scenarios

​Scenario 1: Development Workflow

​Scenario 2: Long-Running Builds

​Scenario 3: Remote Administration

​Scenario 4: Unstable Network Environments

​Session Management

​Built-in UI Multi-Session (v1.1.0+)

​Traditional Multiple Sessions

​Session Discovery

​Keyboard Shortcuts

​Advanced Features

​Predictive Echo (v1.1.0+)

​Tunnel-Only Mode (v1.1.0+)

​IPv6 Support (v1.1.0+)

​Disconnecting vs. Exiting

​Client Disconnect (Safe)

​Shell Exit (Dangerous)

​Scripting and Automation

​Connection Script

​Automated Commands

​Monitoring and Logging

​Client-Side Logging

​Check Connection Status

​Tips and Tricks

​Next Steps

Port Forwarding

SSH Bootstrap

Configuration

Troubleshooting

Daily Workflow

Starting Your Day

Ending Your Day

Common Commands

Interactive Session

One-Shot Commands

Built-in UI Mode

SSH Bootstrap (Remote Servers)

Practical Scenarios

Scenario 1: Development Workflow

Scenario 2: Long-Running Builds

Scenario 3: Remote Administration

Scenario 4: Unstable Network Environments

Session Management

Built-in UI Multi-Session (v1.1.0+)

Traditional Multiple Sessions

Session Discovery

Keyboard Shortcuts

Advanced Features

Predictive Echo (v1.1.0+)

Tunnel-Only Mode (v1.1.0+)

IPv6 Support (v1.1.0+)

Disconnecting vs. Exiting

Client Disconnect (Safe)

Shell Exit (Dangerous)

Scripting and Automation

Connection Script

Automated Commands

Monitoring and Logging

Client-Side Logging

Check Connection Status

Tips and Tricks

Next Steps