# TLL Remote Windows 1.5.5

Windows에 로그인한 사용자 세션에서 PC 에이전트가 동작합니다. Windows용 Tailscale에서 PC와 휴대폰·태블릿을 같은 계정으로 연결하세요. 별도 Codex 개발 도구는 필요하지 않습니다. 태그 또는 공유로 소유자 확인이 불가능한 장치는 사용할 수 없습니다.

PC 에이전트는 Windows에 포함된 .NET Framework를 사용하는 보조 프로세스 하나로 Tailscale 신원을 조회합니다. 매 요청에서 PC와 상대 기기의 신원을 확인하고 결과를 저장하지 않습니다. 보호된 Tailscale 파이프를 열 수 없거나 응답으로 신원을 확인할 수 없으면 요청을 처리하지 않습니다. 사용 중인 Tailscale에서 `status?peers=false`로 PC 소유자를 확인할 수 있어야 합니다.

## 설치 및 업데이트

1. 공식 HTTPS 배포 페이지에서 Windows ZIP과 ZIP 및 `release.json`의 SHA-256을 확인하세요. ZIP 해시를 먼저 비교하고, 로컬 고정 드라이브에 압축을 풉니다.
2. 원격으로 사용할 Windows 계정의 일반 권한 세션에서 `setup.cmd`를 더블클릭합니다. 공식 배포 해시를 자동 확인하고, Tailscale 연결 → 내 휴대폰·집 태블릿 선택 → 설치와 등록 → 휴대폰으로 이어가기 순서로 안내합니다. 같은 계정의 기기를 목록에서 선택하고, 변경 안내에 `Y`를 입력해야 적용됩니다. 마지막에 표시된 PC 주소를 Android 앱의 **연결 도우미**에 입력하세요. MAC 주소와 중계키는 자동으로 가져옵니다. 공식 Node 실행 파일이 포함돼 추가 개발 도구는 필요 없습니다. 공식 배포 정보 조회가 안 되면 해시를 직접 확인하는 대체 경로를 안내합니다.
3. 기본 설치는 현재 사용자 아래의 에이전트, 로그온 작업 하나와 앱 요청 작업만 관리합니다. 앱 작업은 해당 사용자 세션에서 설치된 앱을 실행합니다. Codex 재시작은 확인된 Codex 패키지의 해당 세션 창에 정상 종료를 요청합니다. 창이 닫히지 않으면 강제 종료하지 않습니다.
4. 상대 기기에서 PC 포트로 접속할 수 없다면 관리자에게 방화벽 계획을 확인하도록 요청하세요. `firewall.ps1`은 설치 사용자의 Windows SID와 TCP 포트로 규칙을 식별하고, 지정한 PC의 Tailscale IPv4·인터페이스·Node 실행 파일로 범위를 좁힙니다. 승인할 경우에만 `-Apply`를 붙입니다. 광범위한 Windows 방화벽 허용 팝업은 승인하지 마세요.

```powershell
.\install.ps1 -ExpectedManifestSha256 $publishedManifestSha256
.\install.ps1 -ExpectedManifestSha256 $publishedManifestSha256 -Apply
.\install.ps1 -Mode Status
.\firewall.ps1 -Port 8766 -LocalAddress $pcTailscaleIPv4 -NodePath $installedNodeExe
.\firewall.ps1 -Port 8766 -LocalAddress $pcTailscaleIPv4 -NodePath $installedNodeExe -Apply
```

다운로드 표식 때문에 검증된 수동 스크립트 실행이 차단되면 `setup.cmd`를 사용하거나, ZIP·매니페스트와 해당 스크립트 해시를 확인한 뒤 해당 파일만 `Unblock-File` 하세요. 회사 정책에서 차단하면 관리자에게 문의하세요.

- Node를 번들한 경우 `$installedNodeExe`는 `$env:LOCALAPPDATA\TLL Remote\agent\node.exe`입니다. 시스템 Node를 쓴 경우 설치 때 사용한 공식 `node.exe`의 절대 경로입니다. 방화벽 적용은 패키지 검증과 에이전트 실행을 한 일반 계정 단계와 분리합니다.
- 별도 관리자 계정에서 방화벽을 적용하는 경우, 설치한 사용자의 세션에서 `[Security.Principal.WindowsIdentity]::GetCurrent().User.Value`를 확인하고 계획과 적용에 같은 `-InstallUserSid`를 전달하세요.
- 설치 시 활성 물리 NIC의 MAC과 IPv4 프리픽스에서 LAN 브로드캐스트를 구합니다. 여러 NIC가 활성 상태면 `-LanInterfaceAlias 'Ethernet'`처럼 Windows에 표시되는 정확한 이름을 지정하세요. 업데이트는 저장된 NIC 설정을 유지합니다. NIC를 변경할 때만 `-RefreshLanSettings` 또는 `-LanInterfaceAlias`를 사용하세요.
- `-RelayAddress`는 Tailscale IPv4(`100.64.0.0/10`)와 선택 포트를 받습니다. 예: `-RelayAddress '100.64.0.12:8767'`. 옵션 생략 시 기존 Tailscale 주소가 유지됩니다. 이전 사설 LAN 중계 주소는 비활성화되며, 기기 등록과 직접 LAN WOL은 유지됩니다. 새 설치에서 비워 두거나 `-RelayAddress ''`로 지우면 직접 LAN WOL만 사용합니다.
- 이전 개인 설치는 새 설치로 자동 전환하지 않습니다. 원본 PC의 `trusted-nodes.json`을 패키지 밖의 로컬 경로에 백업하고 최초 설치에 `-LegacyTrustPath $backupPath`를 명시하세요. 가져온 StableID도 호출 때 같은 소유자로 확인되어야 합니다. 기존 에이전트가 대상 포트를 쓰면 설치는 중단되며 기존 작업이나 프로세스는 자동 종료되지 않습니다. 전환이 필요한 경우 담당자가 기존 설치 상태와 원래 복원 경로를 먼저 확인하세요.
- 상태 확인은 Tailscale 자기 신원 및 설치된 버전이 지정 주소·포트를 실제 수신하는 프로세스인지 보여 줍니다. 폰에서 `/health`와 설정 가져오기가 되는지는 별도로 확인하세요. 설치 중 검증이 실패하면 이전 파일, 작업, 설정으로 돌아갑니다. `rollback_incomplete`가 나오면 임시 백업을 삭제하거나 다시 설치하기 전에 담당자에게 문의하세요.

## 기기 등록·제거와 설정

PC에서 본인의 휴대폰 또는 태블릿에 표시된 Tailscale IPv4를 확인하세요. PC에서 `tailscale whois --json`의 `Node.StableID`와 아래 명령의 ID가 정확히 일치해야 합니다. 등록은 소유자 일치도 확인합니다. 계획을 먼저 실행하고 적용할 때만 `--apply`를 붙입니다.

```powershell
$agentDir = Join-Path $env:LOCALAPPDATA 'TLL Remote\agent'
$node = Join-Path $agentDir 'node.exe'  # 외부 Node 설치에서는 사용한 node.exe 경로
$config = Join-Path $agentDir 'config.mjs'
$phoneIp = '100.64.0.11'  # 예시: 자신의 기기에 표시된 주소로 변경
$phoneId = (tailscale whois --json $phoneIp | ConvertFrom-Json).Node.StableID
& $node $config register --ip $phoneIp --id $phoneId
& $node $config register --ip $phoneIp --id $phoneId --apply
& $node $config remove --id $phoneId
& $node $config remove --id $phoneId --apply
```

로컬 설정은 `%USERPROFILE%\.tll-remote\agent-config.json`입니다. `ownerLogin`은 Tailscale이 PC 자기 신원에 보고한 로그인과, `selfStableId`는 같은 PC의 StableID와 일치해야 합니다. 계정을 옮길 때는 옛 설정을 비공개로 백업하고 새 계정에서 빈 목록으로 초기화한 뒤 기기를 다시 등록하세요. `port` 기본값은 `8766`이며 `1024`~`65535`를 지원합니다. 로컬 JSON을 수정하거나 설치의 `-Port`로 변경할 수 있습니다. 포트를 바꾼 뒤 동일한 설치 경로로 작업을 갱신하고 방화벽·클라이언트 포트도 맞추세요. 기본 포트만 지원하는 Android 빌드에서는 `8766`을 유지하세요.

등록된 휴대폰과 태블릿에서 각각 PC Tailscale 주소를 입력하고 **PC 설정 가져오기**를 실행합니다. `GET /setup`은 `schemaVersion: 1`, `pcHost`(포트 없는 Tailscale IPv4), `pcMac`, `lanBroadcast`, `relayAddress`, `relayToken`, `relayRevision`을 반환합니다. 키와 설정 파일 전체를 채팅이나 로그에 붙이지 마세요.

등록 기기를 제거하면 PC API 접근이 즉시 해제되고 중계 키는 무작위 32바이트 값으로 자동 교체됩니다. 제거 결과의 `pcAccessRevoked`는 PC 접근 해제 결과입니다. `config.mjs check`와 `/health`의 `relaySyncPending`이 `true`이면 중계기가 새 키를 적용했다는 확인이 아직 없습니다. 현재 중계 주소의 등록 기기가 새 키를 적용하고 `POST /relay/ack`로 현재 `relayRevision`을 확인하면 대기 표시가 해제됩니다.

## 제거와 지원 범위

```powershell
.\install.ps1 -Mode Uninstall
.\install.ps1 -Mode Uninstall -Apply
.\firewall.ps1 -Mode Remove -Port 8766 -LocalAddress $pcTailscaleIPv4 -NodePath $installedNodeExe
.\firewall.ps1 -Mode Remove -Port 8766 -LocalAddress $pcTailscaleIPv4 -NodePath $installedNodeExe -Apply
```

압축을 푼 원본 폴더에서 제거를 실행하세요. 제거는 해당 계정의 관리 작업과 설치 파일만 삭제하며, 재설치를 위해 사용자 설정과 로그는 보존합니다. 방화벽 규칙 제거에는 생성 시와 같은 설치 사용자 SID, 포트, Tailscale IPv4, Node 절대 경로를 사용하세요. SID가 없는 예전 규칙과 범위가 다른 규칙은 자동으로 제거하지 않습니다. 로그인 정책, 자동 로그인, 부트 메뉴, OpenSSH, Tailscale 서비스 설정은 변경하지 않습니다.

설정까지 지우려면 제거를 마친 뒤 `%USERPROFILE%\.tll-remote\agent-config.json`을 삭제하세요. 진단 로그는 같은 폴더의 `logs\pc-agent.log`입니다. `.tll-remote` 폴더 전체에는 다른 개인용 도구가 있을 수 있으므로 통째로 삭제하지 마세요.

PC 전원 및 앱 명령은 에이전트와 해당 Windows 세션이 작동할 때만 처리됩니다. 재부팅 후 로그인 전에는 기본 설치의 PC API를 사용할 수 없습니다. WOL은 PC·NIC·펌웨어·전원 상태가 WOL을 지원하고, 동일 LAN의 폰 또는 태블릿이 신호를 보낼 수 있을 때만 작동합니다. OS가 완전히 멈춘 PC를 강제로 리셋하지는 못합니다.

## 연결을 끝내는 순서와 분실 기기

Android의 **연결 도우미**는 Tailscale 열기, PC 설치, 이 기기 등록, 설정 가져오기, 연결 확인을 순서대로 제공합니다. 다른 앱에서 로그인·연결을 한 다음 돌아와 다시 확인하세요. 집 태블릿에서는 같은 설정을 가져온 뒤 중계 모드를 켭니다. PC 연결 확인과 중계기 연결 확인은 실제 응답을 기준으로 따로 표시합니다.

원격 켜기를 준비하려면 PC 제조사 안내에 따라 BIOS/UEFI와 유선 랜카드의 Wake-on-LAN을 켜고, 대기 전원과 집 네트워크 연결을 유지하세요. Windows 빠른 시작과 종료 상태의 지원 여부는 제조사·드라이버에 따라 다릅니다. BIOS 변경, 실제 종료·부팅 시험, 로그인 전 접근은 앱 설치만으로 확인되지 않습니다.

휴대폰을 잃어버렸다면 [Tailscale 관리 화면](https://login.tailscale.com/admin/machines)에서 해당 기기의 연결을 제거하고 PC의 등록 목록에서도 제거하세요. PC에서 키를 바꿔도 오프라인 중계기에는 새 키가 아직 도착하지 않을 수 있습니다. `relaySyncPending=false`를 확인하거나 집 태블릿에서 중계 모드를 끄세요. 이 앱의 등록 제거는 별도로 만든 OpenSSH 키나 다른 원격 접속 도구의 권한을 제거하지 않습니다.

Tailscale Personal의 무료 조건은 비상업적 개인 사용에 적용됩니다. 업무용·상업적 이용은 [공식 요금](https://tailscale.com/pricing)을 확인하세요. 고객의 PC 제어를 위해 별도 클라우드 서버를 설치할 필요는 없으며, 인터넷·기기 전력과 서비스 운영자의 배포 인프라 비용까지 0원이라는 뜻은 아닙니다.

## 공개 ZIP 만들기

릴리스에 사용할 소스에서 `.\pc\build-tailscale-localapi.ps1`을 실행해 `pc/tailscale-localapi.exe`를 빌드합니다. 빈 스테이징 폴더에 `setup.cmd`, `setup.ps1`, `install.ps1`, `firewall.ps1`, `agent.mjs`, `config.mjs`, `tailscale-localapi.mjs`, `tailscale-localapi.exe`, `agent-task.ps1`, `app-task.ps1`, `README.md`만 복사합니다. 해당 Windows 아키텍처의 공식 Node LTS를 배포자 서명 해시로 검증한 뒤 `node.exe`와 함께 제공된 라이선스를 `NODE-LICENSE.txt` 이름으로 추가하는 것을 기본으로 합니다. APK는 별도 서명 검증이 끝난 정식 빌드만 `tll-remote.apk`로 포함할 수 있습니다. 개인 관리·자동 로그인·SSH 파일, 기기 목록, 기존 설정·키는 ZIP에 넣지 마세요.

```powershell
$manifestText = node .\pc\make-release-manifest.mjs $stage
if ($LASTEXITCODE -ne 0) { throw '배포 파일 검증 실패' }
$manifestText | Set-Content -LiteralPath (Join-Path $stage 'release.json') -Encoding UTF8
Get-FileHash -LiteralPath (Join-Path $stage 'release.json') -Algorithm SHA256
```

스테이징 파일과 `release.json`을 ZIP으로 묶고 공식 HTTPS 페이지에 버전·아키텍처·ZIP 해시·매니페스트 해시를 게시합니다. 설치 실행 전 독립 해시 확인, 설치 이후 실제 Android `/setup`과 중계 WOL 검증은 릴리스 담당 단계입니다.