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

# Installation

> Detailed installation and setup instructions for Undying Terminal

## System Requirements

### Minimum Requirements

| Component            | Requirement                                       |
| -------------------- | ------------------------------------------------- |
| **Operating System** | Windows 10 (Build 17763+) or Windows Server 2019+ |
| **RAM**              | 256 MB (minimal overhead)                         |
| **Disk Space**       | 50 MB for binaries                                |
| **Network**          | TCP connectivity (port 2022 by default)           |

<Info>
  ConPTY support requires Windows 10 Build 17763 (October 2018 Update) or later.
</Info>

### Recommended Requirements

* Windows 10 21H2 or later / Windows 11
* Windows Terminal (for best terminal experience)
* Dedicated network port for the server
* Administrator access (for Windows Service installation)

## Installation Methods

<Tabs>
  <Tab title="Binary Release (Recommended)">
    ### Download Pre-Built Binaries

    <Steps>
      <Step title="Download">
        Visit the [GitHub Releases](https://github.com/Microck/UndyingTerminal/releases) page and download the latest `undying-terminal-X.X.X-win64.zip`.
      </Step>

      <Step title="Extract">
        Extract the archive to your preferred location:

        ```powershell theme={null}
        # PowerShell
        Expand-Archive -Path undying-terminal-1.0.0-win64.zip -DestinationPath "C:\Program Files\UndyingTerminal"
        ```
      </Step>

      <Step title="Verify">
        Check that all executables are present:

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

        Expected files:

        * `undying-terminal.exe` (client)
        * `undying-terminal-server.exe` (server)
        * `undying-terminal-terminal.exe` (terminal)
        * Required DLLs (libsodium, OpenSSL, etc.)
      </Step>

      <Step title="Add to PATH (Optional)">
        For system-wide access:

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

        # Refresh current session
        $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine')
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build from Source">
    ### Build from Source

    <Steps>
      <Step title="Prerequisites">
        Install required build tools:

        * Visual Studio 2019+ (with C++ Desktop Development workload)
        * CMake 3.20+
        * vcpkg (for dependencies)
        * Git

        ```powershell theme={null}
        # Install vcpkg
        git clone https://github.com/Microsoft/vcpkg.git
        cd vcpkg
        .\bootstrap-vcpkg.bat
        .\vcpkg integrate install
        ```
      </Step>

      <Step title="Clone Repository">
        ```powershell theme={null}
        git clone https://github.com/Microck/UndyingTerminal.git
        cd undyingterminal
        ```
      </Step>

      <Step title="Install Dependencies">
        vcpkg will automatically install dependencies listed in `vcpkg.json`:

        * OpenSSL
        * libsodium
        * Protobuf

        ```powershell theme={null}
        # Automatic via CMake integration
        cmake --preset windows
        ```
      </Step>

      <Step title="Build">
        ```powershell theme={null}
        # Configure
        cmake --preset windows

        # Build (Release)
        cmake --build --preset windows --config Release

        # Output will be in: build/Release/
        ```
      </Step>

      <Step title="Run Tests (Optional)">
        ```powershell theme={null}
        cd build
        ctest -C Release --output-on-failure
        ```
      </Step>
    </Steps>

    <Note>
      For MSYS2/MinGW builds, use the `windows-mingw-msys2` preset:

      ```bash theme={null}
      cmake --preset windows-mingw-msys2
      cmake --build build-mingw
      ```
    </Note>
  </Tab>

  <Tab title="Package Manager">
    ### Package Manager Installation

    <Warning>
      Not available.
    </Warning>
  </Tab>
</Tabs>

## Initial Setup

### 1. Server Setup

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

  <Step title="Create Configuration File">
    Create `ut.cfg` in the config directory:

    ```powershell theme={null}
    $configFile = "$env:PROGRAMDATA\UndyingTerminal\ut.cfg"

    @"
    # Undying Terminal Server Configuration

    # Server listen port (default: 2022)
    port=2022

    # Bind IP (0.0.0.0 = all interfaces)
    bind_ip=0.0.0.0

    # Verbose logging (true/false)
    verbose=false

    # Optional: Shared encryption key (hex)
    # shared_key_hex=<generate-this>
    "@ | Out-File -FilePath $configFile -Encoding ASCII
    ```
  </Step>

  <Step title="Configure Firewall">
    Allow inbound connections on port 2022:

    <CodeGroup>
      ```powershell Automatic (Recommended) theme={null}
      # Run server with --add-firewall once
      ./undying-terminal-server.exe --add-firewall
      ```

      ```powershell Manual theme={null}
      # PowerShell (Run as Administrator)
      New-NetFirewallRule `
        -DisplayName "Undying Terminal Server" `
        -Direction Inbound `
        -Protocol TCP `
        -LocalPort 2022 `
        -Action Allow `
        -Profile Any
      ```
    </CodeGroup>
  </Step>

  <Step title="Start Server (Test)">
    ```powershell theme={null}
    ./undying-terminal-server.exe
    ```

    Expected output:

    ```
    [INFO] Loading config from: C:\ProgramData\UndyingTerminal\ut.cfg
    [INFO] Server listening on 0.0.0.0:2022
    [INFO] Named pipe server started: \\.\pipe\undying-terminal
    ```
  </Step>
</Steps>

### 2. Windows Service Installation (Production)

For production environments, run the server as a Windows service:

<CodeGroup>
  ```powershell Install Service theme={null}
  # PowerShell (Run as Administrator)
  sc.exe create UndyingTerminalServer `
    binPath= "C:\Program Files\UndyingTerminal\undying-terminal-server.exe --service" `
    start= auto `
    DisplayName= "Undying Terminal Server"

  # Start the service
  sc.exe start UndyingTerminalServer
  ```

  ```powershell Verify Service theme={null}
  # Check service status
  sc.exe query UndyingTerminalServer

  # View service properties
  Get-Service UndyingTerminalServer | Format-List *
  ```

  ```powershell Uninstall Service theme={null}
  # Stop and remove service
  sc.exe stop UndyingTerminalServer
  sc.exe delete UndyingTerminalServer
  ```
</CodeGroup>

<Tip>
  Service mode automatically handles job object cleanup and runs with system privileges.
</Tip>

### 3. Client Setup

No special setup required for the client! Just run:

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

## Verification

### Test Local Connection

<Steps>
  <Step title="Start Server">
    ```powershell theme={null}
    # Terminal 1
    ./undying-terminal-server.exe
    ```
  </Step>

  <Step title="Start Terminal">
    ```powershell theme={null}
    # Terminal 2
    echo "test/ignored" | ./undying-terminal-terminal.exe
    ```

    Note the `client_id` and `passkey` from output.
  </Step>

  <Step title="Connect Client">
    ```powershell theme={null}
    # Terminal 3
    ./undying-terminal.exe `
      --connect 127.0.0.1 2022 <CLIENT_ID> `
      --key <PASSKEY> `
      --noexit
    ```
  </Step>

  <Step title="Test Session">
    Type `dir` or `ls` and verify output appears.
  </Step>
</Steps>

<Check>
  If you see command output, installation is successful!
</Check>

## Network Configuration

### Port Forwarding (Router/Firewall)

To access the server from outside your local network:

<Steps>
  <Step title="Find Server IP">
    ```powershell theme={null}
    # Internal IP
    ipconfig | findstr IPv4

    # External IP (public)
    (Invoke-WebRequest -Uri "https://api.ipify.org").Content
    ```
  </Step>

  <Step title="Configure Port Forwarding">
    In your router:

    * Forward external port 2022 → internal IP:2022
    * Use TCP protocol
    * Enable the rule
  </Step>

  <Step title="Test External Access">
    ```powershell theme={null}
    # From external network
    ./undying-terminal.exe --connect <PUBLIC_IP> 2022 <CLIENT_ID> --key <PASSKEY>
    ```
  </Step>
</Steps>

<Warning>
  **Security Recommendation**: Enable shared key encryption when exposing the server to the internet. See [Configuration → Encryption](/config/server-config#encryption).
</Warning>

## Optional Enhancements

### Generate Encryption Key

For production deployments with encryption:

```powershell theme={null}
# Generate random 32-byte hex key
$bytes = New-Object byte[] 32
[Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($bytes)
$hexKey = -join ($bytes | ForEach-Object { $_.ToString("x2") })
Write-Output "shared_key_hex=$hexKey"

# Add to ut.cfg
```

### Install Dependencies (MSYS2)

If using MSYS2 builds:

```bash theme={null}
# MSYS2 MINGW64 shell
pacman -S mingw-w64-x86_64-cmake \
          mingw-w64-x86_64-gcc \
          mingw-w64-x86_64-protobuf \
          mingw-w64-x86_64-libsodium \
          mingw-w64-x86_64-openssl
```

## Troubleshooting Installation

<AccordionGroup>
  <Accordion title="Missing DLL errors">
    If you see errors like:

    ```
    The code execution cannot proceed because libsodium.dll was not found.
    ```

    **Solution**:

    * Ensure all DLLs from the release package are in the same directory as the executables
    * Check `PATH` includes the installation directory
    * Reinstall Visual C++ Redistributable (2015-2022)
  </Accordion>

  <Accordion title="Build errors with vcpkg">
    If CMake can't find dependencies:

    ```powershell theme={null}
    # Ensure vcpkg integration is active
    cd \path\to\vcpkg
    .\vcpkg integrate install

    # Point CMake to vcpkg
    cmake -DCMAKE_TOOLCHAIN_FILE=\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake ..
    ```
  </Accordion>

  <Accordion title="ConPTY not available">
    Error: `CreatePseudoConsole failed`

    **Cause**: Windows version \< Build 17763

    **Solution**: Update Windows to October 2018 Update (Build 17763) or later
  </Accordion>

  <Accordion title="Port 2022 already in use">
    Check what's using the port:

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

    Options:

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Start using Undying Terminal
  </Card>

  <Card title="Server Configuration" icon="gear" href="/config/server-config">
    Configure advanced server options
  </Card>

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

  <Card title="Building from Source" icon="code" href="/development/building">
    Detailed build instructions
  </Card>
</CardGroup>

## System Integration Checklist

Before deploying to production:

* [ ] Installed binaries to `C:\Program Files\UndyingTerminal`
* [ ] Created config file at `%PROGRAMDATA%\UndyingTerminal\ut.cfg`
* [ ] Configured firewall rule (auto or manual)
* [ ] Tested local connection (server → terminal → client)
* [ ] Generated encryption key (for external access)
* [ ] Installed as Windows service (optional)
* [ ] Configured port forwarding (if remote access needed)
* [ ] Tested remote connection (if applicable)
* [ ] Set up monitoring/logging (optional)