> ## Documentation Index
> Fetch the complete documentation index at: https://undyingterminal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Undying Terminal

> Persistent SSH sessions on Windows that survive network interruptions

## Welcome to Undying Terminal

Undying Terminal is a **Windows-native persistent terminal solution** that keeps your SSH sessions alive through network disconnects, VPN switches, laptop sleep, and other interruptions that would normally kill your terminal session.

## The Problem We Solve

Traditional SSH sessions are fragile. They break when:

* Your network connection drops
* Your laptop goes to sleep
* You switch VPN connections
* You change WiFi networks
* Your connection times out

**Result**: Lost work, interrupted processes, and frustration.

## The Undying Terminal Solution

Undying Terminal implements a **client-server-terminal architecture** with:

<CardGroup cols={2}>
  <Card title="Automatic Reconnection" icon="rotate">
    Detects disconnects and reconnects seamlessly with exponential backoff
  </Card>

  <Card title="Session Recovery" icon="shield-check">
    Sequence-based protocol recovers missed packets (up to 64MB buffer)
  </Card>

  <Card title="End-to-End Encryption" icon="lock">
    Optional XSalsa20 encryption via libsodium for secure communication
  </Card>

  <Card title="SSH Bootstrap" icon="terminal">
    Start remote terminals over SSH, then maintain them over TCP
  </Card>
</CardGroup>

## Key Features

### Persistent Sessions

Your terminal stays alive even when:

* Network disconnects occur
* Laptop sleeps/wakes
* VPN switches happen
* WiFi changes

### Port Forwarding

<CodeGroup>
  ```powershell Forward Tunnels theme={null}
  # Local 8080 → Remote 9090
  ./undying-terminal.exe --connect 127.0.0.1 2022 <id> -t 8080:9090
  ```

  ```powershell Reverse Tunnels theme={null}
  # Server listens on 3000, client connects to local service
  ./undying-terminal.exe --connect 127.0.0.1 2022 <id> -r 3000:localhost:8000
  ```
</CodeGroup>

### Jumphost Support

Connect through intermediate jump servers:

```mermaid theme={null}
flowchart LR
    C[Client] --> J[Jump Server]
    J --> D[Destination]
    style C fill:#fc6505
    style J fill:#3e4954,color:#fff
    style D fill:#3e4954,color:#fff
```

### Keepalive & Recovery

* Automatic heartbeat packets (default 5s)
* Detects dead connections (3 missed → reconnect)
* Sequence-based recovery (resends missed packets)

## Architecture

Undying Terminal consists of three components:

<Steps>
  <Step title="Server">
    **undying-terminal-server.exe**

    Central session manager listening on TCP (default port 2022). Maintains client registry and handles authentication.
  </Step>

  <Step title="Terminal">
    **undying-terminal-terminal.exe**

    ConPTY-based terminal that spawns shell processes and connects to the server via named pipe.
  </Step>

  <Step title="Client">
    **undying-terminal.exe**

    User-facing client that handles I/O, reconnection, tunnels, and SSH bootstrap.
  </Step>
</Steps>

## Use Cases

<AccordionGroup>
  <Accordion title="Remote Development" icon="code">
    Keep long-running build processes alive even when your network drops. Perfect for remote development workflows where interruptions are costly.
  </Accordion>

  <Accordion title="System Administration" icon="server">
    Maintain persistent connections to remote servers during system updates, backups, or maintenance tasks that take hours.
  </Accordion>

  <Accordion title="Mobile/Unstable Networks" icon="wifi">
    Work from coffee shops, trains, or mobile hotspots without losing your terminal sessions when switching networks.
  </Accordion>

  <Accordion title="Laptop Users" icon="laptop">
    Close your laptop lid mid-session without losing your work. Sessions survive sleep/wake cycles.
  </Accordion>
</AccordionGroup>

## Platform Support

| Platform             | Status          | Notes                   |
| -------------------- | --------------- | ----------------------- |
| Windows 10+          | Fully Supported | Primary target platform |
| Windows Server 2019+ | Fully Supported | Service mode available  |

<Note>
  Undying Terminal is Windows-only.
</Note>

## Performance Characteristics

| Metric             | Value               | Notes                      |
| ------------------ | ------------------- | -------------------------- |
| Recovery Buffer    | 64MB                | Packets stored for catchup |
| Keepalive Interval | 5s (configurable)   | Heartbeat frequency        |
| Reconnect Backoff  | 100ms → 2000ms      | Exponential backoff        |
| Missed Heartbeats  | 3 before disconnect | Configurable threshold     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running in 5 minutes
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation instructions
  </Card>

  <Card title="Architecture Deep Dive" icon="diagram-project" href="/architecture/overview">
    Understand how it works under the hood
  </Card>

  <Card title="Configuration" icon="gear" href="/config/server-config">
    Configure server and client options
  </Card>
</CardGroup>