What is a Persistent Session?
A persistent session is a terminal connection that survives network interruptions, computer sleep/wake cycles, and connection quality issues. Unlike traditional SSH, where a dropped connection kills your running processes, Undying Terminal keeps your session alive indefinitely.
How It Works
Session Lifecycle
Component Roles
Server (undying-terminal-server.exe)
- Maintains session registry
- Routes traffic between clients and terminals
- Enforces encryption
- Handles authentication
Terminal (undying-terminal-terminal.exe)
- Manages the actual shell process (cmd.exe, PowerShell, etc.)
- Buffers output using ConPTY
- Survives client disconnections
- Persists until explicitly terminated
Client (undying-terminal.exe)
- User-facing interface
- Reconnects automatically on disconnect
- Can be closed and restarted without affecting session
Session Recovery
Sequence-Based Protocol
Every packet exchanged between client and terminal has a sequence number. When reconnecting:
- Client sends last received sequence number
- Server checks recovery buffer (64MB circular buffer)
- Server replays all missed data
- Session resumes exactly where it left off
Example:
Buffer Capacity
If the recovery buffer fills up during a long disconnect, older data is discarded. The connection will still recover, but you’ll see a gap in output.
Persistence Guarantees
What Survives
Network disruptions:
- WiFi disconnects
- Ethernet unplugs
- VPN reconnections
- IP address changes
- Router reboots
System events:
- Laptop sleep/wake
- Hibernate/resume
- Screen lock/unlock
- User switching
Client crashes:
- Client process killed
- Terminal emulator closed
- Client machine reboot (server keeps session)
What Doesn’t Survive
Server process termination:
- Server crash or restart kills all terminals
- Solution: Run server as Windows service
Terminal process termination:
- Manual kill of terminal process
- Server machine reboot
- Shell process exits cleanly
Explicit session termination:
- Running
exit in the shell
- Sending
Ctrl+C to terminal process
- Manual cleanup via server
Session Identification
Every terminal session is identified by:
Client ID (8-char hex)
- Randomly generated when terminal starts
- Used to identify which session to connect to
- Stable across client reconnections
Passkey (optional, 32-char hex)
- Enables encryption (XSalsa20)
- Acts as authentication credential
- Required if server configured with
require_key
Comparison to Traditional SSH
Session Management
Listing Active Sessions
Server maintains a registry of all active terminals. Connect to server console to view:
Terminating Sessions
Graceful exit:
Force kill terminal:
Clean up orphaned sessions:
Server automatically detects when terminal processes die and removes them from the registry.
Advanced Session Features
Multiple Clients to One Session
Multiple clients can connect to the same terminal session simultaneously:
Both clients see the same output and can send input. Useful for:
- Screen sharing without screen sharing tools
- Pair programming
- Training/demonstrations
Session Timeouts
Server does NOT implement idle timeouts by default. Sessions remain active until:
- Terminal process exits
- Server process exits
- Manual termination
To implement your own timeout, use shell-level mechanisms:
Best Practices
For remote work:
- Run server as Windows service (survives server reboots)
- Use encryption (
--key) on untrusted networks
- Save connection commands as scripts
- Monitor server logs for security events
For high-reliability needs:
- Increase buffer size in server config (if dealing with high output volume)
- Set up monitoring/alerts if server goes down
- Use named sessions (via wrapper scripts) for easier reconnection
For security:
- Always use encryption on public networks
- Firewall server port (2022) to trusted IPs only
- Rotate passkeys periodically
- Enable server logging for audit trails
Next Steps
