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

# In the persistent session:
cd C:\projects\myapp
npm run dev

# Close laptop, go home
# Next day: reconnect (same command)
./undying-terminal.exe --connect 127.0.0.1 2022 <ID> --key <KEY> --noexit

# Your npm dev server is still running!

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

# In the persistent session on prod-server:
# Start long-running backup
./backup-script.ps1

# Disconnect laptop, go to meeting
# Session continues running

# Reconnect later to check status
./undying-terminal.exe --connect prod-server.com 2022 <ID> --key <KEY>

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

# Terminal 2 (with different pipe)
$env:UT_PIPE_NAME = "\\\\.\\pipe\\undying-terminal-prod"
echo "prod" | ./undying-terminal-terminal.exe
# client_id: prod-001, passkey: def456

# Connect to prod session
./undying-terminal.exe --connect 127.0.0.1 2022 prod-001 --key def456 --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

# connect-prod.ps1 (with encryption!)
$clientId = "prod-client-id"
$passkey = "prod-passkey"

./undying-terminal.exe `
  --connect prod-server.com 2022 $clientId `
  --key $passkey `
  --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"

# Windows Task Scheduler
$action = New-ScheduledTaskAction `
  -Execute "PowerShell.exe" `
  -Argument "-File C:\scripts\run-backup.ps1"

$trigger = New-ScheduledTaskTrigger -Daily -At 2am

Register-ScheduledTask `
  -TaskName "Nightly Backup via Undying Terminal" `
  -Action $action `
  -Trigger $trigger

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

​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