Files

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.

Desktop installers

Run scripts/build-installers.ps1 from the repository root to build separate Avalonia and Flutter Windows x64 installers. Requires Inno Setup 6/7 (-Compiler selects ISCC.exe). Build Rust binaries first with scripts/build.ps1; -SkipBuild packages existing release folders. -Edition Avalonia or Flutter selects one client. Outputs and SHA-256 sidecars are in bin/installers/.

Installers use per-user installation, Start menu entries, optional desktop shortcuts, and Windows uninstall registration. Editions have separate install identities and can coexist; installing the same edition upgrades it in place. Close the client and stop any Agent hosted from its installation folder before upgrading. Credentials, local settings and device configuration are excluded; import credentials after installation. Uninstall retains settings in user data and does not remove separately installed Agent tasks or USB drivers. USB driver installation remains an explicit optional step. Setup executables are currently unsigned; distribution signing requires the publisher certificate.

Windows desktop packages now include the unmodified signed USBip 0.9.8.1 x64 installer under drivers/. Packaging verifies its pinned SHA-256 and publisher signature using scripts/install-windows-usb.ps1. The ADS installer only copies the optional installer; Flutter prompts to install it when USB mode is selected without the controller. Driver installation is interactive and requires the user's UAC approval; no automatic reboot occurs.