Files
AndroidDeviceStreaming/deploy/windows/README.md
T

4.4 KiB
Raw Blame History

Windows device gateway deployment

These scripts install the Rust gateway as a background Scheduled Task. This is not a native Windows Service binary. They require an administrator account to register the startup trigger, and prefer PowerShell 7 when installed.

Installation

Default private directory: %LOCALAPPDATA%\AndroidDeviceStreaming\agent.

  1. Run prepare-agent.ps1 on the target computer. It creates the directory and grants access only to the current account, SYSTEM and Administrators.

  2. Copy the following staged files into that directory:

    Source Staged name
    bin/ads-agent.exe ads-agent.exe.new
    run-agent.ps1 run-agent.ps1.new
    Your edited agent.example.json agent.json.new
    Private agent-role environment file agent.env.new
    install-agent.ps1 install-agent.ps1
  3. Run install-agent.ps1 from that directory. Supply the current Windows account credential at the secure prompt. For an encrypted remote-management channel, -PasswordFromStdin reads the password from standard input rather than the command line. Do not put passwords into scripts.

The installer backs up existing gateway files inside the protected directory, replaces only its own files, and refuses to overwrite an unrelated task with the same name. Its installation path is checked before any process stop or file replacement.

Task ADS-Agent uses password logon so it can run without an interactive desktop session. Windows Task Scheduler stores the account credential; it is not stored in the gateway JSON, environment file or source repository. Re-register the task if the Windows account password changes.

Configured behavior:

  • Startup and account-logon triggers; duplicate instances ignored.
  • Hidden, non-interactive PowerShell runner, with the Rust child in its process tree.
  • No execution time limit; restart on process failure after one minute, up to 999 retries.
  • Rust itself reconnects to the relay with a 1–30 second backoff.
  • agent.json configures relay URL, public origin override, device alias and phone endpoint.
  • agent.env contains only the gateway role credential and optional non-sensitive connection settings.
  • Log: logs/agent.log; rotated on runner start when it exceeds 10 MiB.

Deployed computer

Installed on 192.168.5.222 as account TT:

C:\Users\TT\AppData\Local\AndroidDeviceStreaming\agent

Device: home-phone; target: 192.168.100.141:5555; relay: wss://ttstd.com/ads; public origin: 175.178.213.60:443 with normal domain TLS validation.

Task registration, task restart, executable hash and post-restart public ADB smoke test were verified. Startup triggers were inspected; the computer was not rebooted. The Rust process working set was about 8.7 MiB at the sampled instant, excluding the PowerShell runner.

Management commands on that computer:

Get-ScheduledTask -TaskName ADS-Agent
Get-ScheduledTaskInfo -TaskName ADS-Agent
Get-Content "$env:LOCALAPPDATA\AndroidDeviceStreaming\agent\logs\agent.log" -Tail 30
Start-ScheduledTask -TaskName ADS-Agent
Stop-ScheduledTask -TaskName ADS-Agent

Managed multi-phone Agent (0.2)

The deployed computer has migrated to Agent ID home-pc (家里电脑), retaining home-phone and its TCP endpoint. ADS-Agent-home-pc runs the native supervised Agent as SYSTEM at startup; the old ADS-Agent task is disabled. The migration keeps a timestamped backup under the protected Agent directory and restores the legacy files/task on failure. No reboot was performed.

migrate-managed.ps1 migrates the earlier TCP single-phone installation. Stage the new binaries as ads-agent.exe.new and adsctl.exe.new in its directory, then run the script in an elevated PowerShell 7 terminal. It verifies the legacy task belongs to that directory before stopping it. Parameters customize directory, Agent ID, display name and old task name. New installations should use adsctl init and adsctl service install instead.

For current status and logs, use:

& "$env:LOCALAPPDATA/AndroidDeviceStreaming/agent/adsctl.exe" status
& "$env:LOCALAPPDATA/AndroidDeviceStreaming/agent/adsctl.exe" logs --follow
Get-ScheduledTask -TaskName ADS-Agent-home-pc

The managed log buffer is in memory; the old runner log is historical. See Agent management for Linux and Windows headless setup, CLI commands, role credentials and both GUIs.