> ## 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.

# Quick Start

> Get started with Undying Terminal in 5 minutes

## Prerequisites

Before you begin, ensure you have:

* Windows 10 or later (Windows Server 2019+ also supported)
* Windows Terminal, CMD, or PowerShell
* Downloaded the latest release binaries

<Warning>
  Undying Terminal requires Windows 10+ for ConPTY support. Earlier Windows versions are not supported.
</Warning>

## Installation

<Steps>
  <Step title="Download Binaries">
    Download the latest release from GitHub:

    ```powershell theme={null}
    # Download from releases page
    https://github.com/Microck/UndyingTerminal/releases/latest
    ```

    Extract the archive to a directory (e.g., `C:\Program Files\UndyingTerminal`)
  </Step>

  <Step title="Add to PATH (Optional)">
    Add the installation directory to your PATH for convenience:

    ```powershell theme={null}
    # PowerShell (Run as Administrator)
    $path = [Environment]::GetEnvironmentVariable('Path', 'Machine')
    $newPath = "$path;C:\Program Files\UndyingTerminal"
    [Environment]::SetEnvironmentVariable('Path', $newPath, 'Machine')
    ```
  </Step>

  <Step title="Verify Installation">
    Verify all three executables are present:

    ```powershell theme={null}
    ls C:\Program Files\UndyingTerminal\
    ```

    You should see:

    * `undying-terminal-server.exe`
    * `undying-terminal-terminal.exe`
    * `undying-terminal.exe`
  </Step>
</Steps>

## Basic Usage

### 1. Start the Server

Open a terminal and start the server:

```powershell theme={null}
./undying-terminal-server.exe
```

<Info>
  By default, the server listens on port `2022`. You can change this in the configuration file.
</Info>

Expected output:

```
[INFO] Server listening on 0.0.0.0:2022
[INFO] Named pipe server started: \\.\pipe\undying-terminal
```

### 2. Start a Terminal

In a **new terminal window**, start a terminal session:

```powershell theme={null}
echo "XXX/ignored" | ./undying-terminal-terminal.exe
```

<Note>
  The `echo "XXX/ignored"` provides a dummy stdin input. The terminal will print its **client ID and passkey** on first run - save these for the next step!
</Note>

Expected output:

```
[TERMINAL] Client ID: abc123def456
[TERMINAL] Passkey: 1234567890abcdef
[TERMINAL] Ready for connection
```

### 3. Connect the Client

In a **third terminal window**, connect to the session:

```powershell theme={null}
./undying-terminal.exe `
  --connect 127.0.0.1 2022 abc123def456 `
  --key 1234567890abcdef `
  --noexit
```

<CodeGroup>
  ```powershell Windows Terminal / PowerShell theme={null}
  ./undying-terminal.exe `
    --connect 127.0.0.1 2022 <CLIENT_ID> `
    --key <PASSKEY> `
    --noexit
  ```

  ```cmd CMD theme={null}
  undying-terminal.exe --connect 127.0.0.1 2022 <CLIENT_ID> --key <PASSKEY> --noexit
  ```
</CodeGroup>

You're now connected! Try typing commands - they'll execute in the remote terminal session.

## Testing Session Persistence

Let's verify that your session survives disconnects:

<Steps>
  <Step title="Start a Long-Running Process">
    In your connected terminal, start something that takes time:

    ```powershell theme={null}
    ping -t 8.8.8.8
    ```
  </Step>

  <Step title="Kill the Client">
    Close the client terminal window (or press Ctrl+C)
  </Step>

  <Step title="Reconnect">
    In a new terminal, reconnect using the same command:

    ```powershell theme={null}
    ./undying-terminal.exe `
      --connect 127.0.0.1 2022 abc123def456 `
      --key 1234567890abcdef `
      --noexit
    ```
  </Step>

  <Step title="Verify Recovery">
    You should see:

    * The ping is still running
    * Recent output is replayed (catchup)
    * New output continues streaming
  </Step>
</Steps>

<Check>
  **Success!** Your session survived the disconnect and recovered seamlessly.
</Check>

## One-Shot Commands

Execute a single command without interactive mode:

```powershell theme={null}
# Note: include `r`n for cmd.exe newline
./undying-terminal.exe `
  --connect 127.0.0.1 2022 <CLIENT_ID> `
  --key <PASSKEY> `
  -c "echo Hello World`r`n"
```

The client will:

1. Connect to the session
2. Send the command
3. Wait for output
4. Exit when idle

## SSH Bootstrap (Remote Servers)

Connect to a remote server and start a persistent session:

```powershell theme={null}
./undying-terminal.exe --ssh user@remote-server.com -l username
```

This will:

1. SSH to the remote server
2. Start `undying-terminal-terminal` remotely
3. Extract the client ID and passkey
4. Connect directly via TCP
5. Keep the session alive even if SSH drops

<Tip>
  SSH bootstrap is perfect for remote development servers. After initial setup, your session survives network changes!
</Tip>

### Tmux Integration (v1.1.0+)

For servers with tmux installed, auto-attach to a tmux session:

```powershell theme={null}
./undying-terminal.exe --ssh user@remote-server.com -l username --tmux --tmux-session myproject
```

This combines Undying Terminal's network resilience with tmux's session persistence.

### Predictive Echo (v1.1.0+)

For high-latency connections, enable local echo:

```powershell theme={null}
./undying-terminal.exe --ssh user@remote-server.com -l username --predictive-echo
```

Characters appear instantly while typing, improving responsiveness on slow networks.

## Configuration File (Optional)

Create a config file for persistent settings:

<CodeGroup>
  ```ini ut.cfg theme={null}
  # %PROGRAMDATA%\UndyingTerminal\ut.cfg

  port=2022
  bind_ip=0.0.0.0
  verbose=false
  shared_key_hex=<your-hex-key>
  ```

  ```powershell Create Config Directory theme={null}
  # PowerShell (Run as Administrator)
  $configDir = "$env:PROGRAMDATA\UndyingTerminal"
  New-Item -ItemType Directory -Force -Path $configDir
  ```
</CodeGroup>

## Built-in UI (v1.1.0+)

For managing multiple sessions, use the built-in UI:

```powershell theme={null}
./undying-terminal.exe --ui
```

**Example workflow:**

```text theme={null}
ut-ui> add dev localhost 2022 <client_id> <passkey>
ut-ui> add prod prod-server.com 2022 <client_id> <passkey>
ut-ui> start dev
ut-ui> list
- dev host=localhost port=2022 running=yes
- prod host=prod-server.com port=2022 running=no
ut-ui> quit
```

The UI makes it easy to manage multiple environments without remembering complex commands.

<Card title="Learn More" icon="window-maximize" href="/guides/built-in-ui">
  Full guide to the built-in UI
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Port Forwarding" icon="right-left" href="/guides/port-forwarding">
    Learn how to forward ports through your session
  </Card>

  <Card title="Jumphost Setup" icon="server" href="/guides/jumphost">
    Connect through intermediate servers
  </Card>

  <Card title="Built-in UI" icon="window-maximize" href="/guides/built-in-ui">
    Manage multiple sessions interactively
  </Card>

  <Card title="Windows Service" icon="windows" href="/guides/windows-service">
    Run the server as a Windows service
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server won't start - port already in use">
    Check if port 2022 is already in use:

    ```powershell theme={null}
    netstat -ano | findstr :2022
    ```

    Either:

    * Kill the process using the port
    * Change the port in `ut.cfg`
    * Use `--port` flag: `./undying-terminal-server.exe --port 2023`
  </Accordion>

  <Accordion title="Client can't connect - connection refused">
    Verify:

    1. Server is running (`netstat -ano | findstr :2022`)
    2. Firewall isn't blocking port 2022
    3. Client ID and passkey match terminal output

    Enable verbose logging:

    ```powershell theme={null}
    $env:UT_DEBUG_HANDSHAKE=1
    ./undying-terminal.exe --connect ...
    ```
  </Accordion>

  <Accordion title="Named pipe errors on multi-server setup">
    If running multiple servers on one machine (dev), set unique pipe names:

    ```powershell theme={null}
    # Server 1
    $env:UT_PIPE_NAME="\\\\.\\pipe\\undying-terminal-2022"
    ./undying-terminal-server.exe --port 2022

    # Server 2
    $env:UT_PIPE_NAME="\\\\.\\pipe\\undying-terminal-2023"
    ./undying-terminal-server.exe --port 2023
    ```
  </Accordion>
</AccordionGroup>

## Summary

You've learned how to:

* Install and run all three components
* Create and connect to persistent sessions
* Test session recovery
* Execute one-shot commands
* Use SSH bootstrap for remote servers

<Tip>
  For production use, consider running the server as a Windows service and enabling encryption via `shared_key_hex` in the config file.
</Tip>