The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
# Harness CLI installer for Windows, served from https://cdn.autonomous.ai/harness/cli/install.ps1.
# Source of truth: THIS file, cli/scripts/install.ps1. It is published by cli/scripts/upload-install-ps1.sh (staging
# by default; production is the owner's step) and tested by cli/src/scripts/installPs1.spec.ts. It is the Windows
# counterpart of install.sh, step for step.
#
# irm https://cdn.autonomous.ai/harness/cli/install.ps1 | iex
# iex "& { $(irm https://cdn.autonomous.ai/harness/cli/install.ps1) } -Desktop"
# irm https://cdn.autonomous.ai/harness/desktop/install.ps1 | iex (the desktop app: this file, app line on)
# powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -Manifest C:\build\install-manifest.json -NoService
#
# It installs per user, with no administrator rights. Everything goes under %USERPROFILE%\.harness, and PATH is the
# user's own (HKCU\Environment), never the machine's. The file is pure ASCII on purpose: Windows PowerShell 5.1
# reads a script file without a BOM in the ANSI code page, so one non-ASCII character would garble it.
param(
[switch]$Desktop,
[switch]$App,
[string]$Manifest = $env:HARNESS_INSTALL_MANIFEST,
[switch]$NoService
)
# The base under which the three published manifests live: cli/metadata.json, runtime/metadata.json and
# pty/metadata.json. upload-install-ps1.sh rewrites this one line for the staging copy.
$HarnessManifestBase = 'https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/'
# What a run with no switch installs: the CLI here, and the app in the copy published as desktop/install.ps1.
# upload-install-ps1.sh --app rewrites this one line.
$HarnessInstallApp = $false
# Set when this runs as a file (-File, or a saved copy). It is empty under `irm | iex`.
$HarnessScriptPath = $MyInvocation.MyCommand.Path
$HarnessCliVersionPattern = '^\d+\.\d+\.\d+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$'
$HarnessPtyVersionPattern = '^\d+(\.\d+)*$'
$HarnessPtyFiles = @('harness-pty.exe', 'harness-launch.exe', 'harness.exe', 'conpty.dll', 'OpenConsole.exe', 'harness-serial.exe', 'harness-tui.exe')
function Get-HarnessPlatform {
# The platform from the NATIVE architecture, read where Windows keeps it for the whole system. An x64
# PowerShell emulated on an ARM64 computer reports AMD64 in its own environment, and would install the
# emulated build.
param([string]$Architecture)
if (-not $Architecture) {
$item = Get-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment' -Name PROCESSOR_ARCHITECTURE -ErrorAction SilentlyContinue
if ($item) { $Architecture = [string]$item.PROCESSOR_ARCHITECTURE }
if (-not $Architecture) { $Architecture = [string]$env:PROCESSOR_ARCHITECTURE }
}
switch ($Architecture.ToUpperInvariant()) {
'AMD64' { return 'win32-x64' }
'ARM64' { return 'win32-arm64' }
default { throw "This computer's processor ($Architecture) is not supported: Harness runs on 64-bit Windows, x64 or ARM64." }
}
}
function Test-HarnessHost {
# ConPTY, which the terminal host needs, arrived in Windows 10 1809 (build 17763). tar.exe, which unpacks the
# downloads, has shipped in System32 since 1803. The path is fixed so a GNU tar on PATH is never used: it
# cannot read a zip.
param([int]$Build = [Environment]::OSVersion.Version.Build, [string]$SystemRoot = $env:SystemRoot)
if ($Build -lt 17763) { throw "Harness needs Windows 10 version 1809 or later, and this computer runs build $Build. Update Windows, then run the installer again." }
$tar = Join-Path $SystemRoot 'System32\tar.exe'
if (-not (Test-Path -LiteralPath $tar -PathType Leaf)) { throw "Windows' own tar.exe is missing ($tar). It is part of Windows 10 1803 and later." }
return $tar
}
function Test-HarnessUrl([string]$Value) { return $Value -match '^https://' }
function Test-HarnessScheme([string]$Value) { return $Value -match '^[A-Za-z][A-Za-z0-9+.-]*://' }
function Invoke-HarnessRetry {
# Three tries for a network step, as install.sh's download() makes. A connection that drops in the middle
# of a 30 MB runtime is common on Wi-Fi.
param([scriptblock]$Action, [int]$Attempts = 3)
for ($i = 1; ; $i++) {
try { return & $Action } catch {
if ($i -ge $Attempts) { throw }
Write-Host " Connection interrupted; retrying ($($i + 1)/$Attempts)..."
Start-Sleep -Seconds 2
}
}
}
function Get-HarnessJson {
param([string]$Source)
if (Test-HarnessUrl $Source) {
$response = Invoke-HarnessRetry { Invoke-WebRequest -Uri $Source -UseBasicParsing -TimeoutSec 60 -Headers @{ 'Cache-Control' = 'no-cache' } }
$content = $response.Content
if ($content -is [byte[]]) { $content = [Text.Encoding]::UTF8.GetString($content) }
return $content | ConvertFrom-Json
}
if (Test-HarnessScheme $Source) { throw "Only https:// addresses are trusted, and $Source is not one." }
if (-not (Test-Path -LiteralPath $Source -PathType Leaf)) { throw "The manifest $Source does not exist." }
return (Get-Content -LiteralPath $Source -Raw -Encoding UTF8) | ConvertFrom-Json
}
function Resolve-HarnessRef {
# Where an entry's file is. A published manifest names https:// addresses only. A local manifest (a test, or a
# build of this tree) may also name files beside it.
param([string]$Ref, [string]$ManifestSource)
if (Test-HarnessUrl $Ref) { return $Ref }
if (Test-HarnessScheme $Ref) { throw "Only https:// addresses are trusted, and $Ref is not one." }
if (Test-HarnessUrl $ManifestSource) { throw "The manifest $ManifestSource names $Ref, which is not an https:// address." }
if ([IO.Path]::IsPathRooted($Ref)) { return $Ref }
return Join-Path (Split-Path -Parent $ManifestSource) $Ref
}
function Get-HarnessProperty($Object, [string]$Name) {
if ($null -eq $Object) { return $null }
$property = $Object.PSObject.Properties[$Name]
if ($property) { return $property.Value }
return $null
}
function Get-HarnessManifests {
# The three entries this computer needs, each with the document it came from: relative names in a local
# manifest are resolved against that document. With -Manifest it is one document holding the cli, node and pty
# keys. Otherwise it is the three published documents under $Base.
param([string]$Manifest, [string]$Platform, [string]$Base = $HarnessManifestBase)
if ($Manifest) {
if (-not (Test-HarnessUrl $Manifest) -and -not (Test-HarnessScheme $Manifest)) {
if (-not (Test-Path -LiteralPath $Manifest -PathType Leaf)) { throw "The manifest $Manifest does not exist." }
$Manifest = (Resolve-Path -LiteralPath $Manifest).ProviderPath
}
$document = Get-HarnessJson $Manifest
$sources = @{ cli = $Manifest; node = $Manifest; pty = $Manifest }
$documents = @{ cli = $document; node = $document; pty = $document }
} else {
$sources = @{ cli = "${Base}cli/metadata.json"; node = "${Base}runtime/metadata.json"; pty = "${Base}pty/metadata.json" }
$documents = @{}
foreach ($name in 'cli', 'node', 'pty') { $documents[$name] = Get-HarnessJson $sources[$name] }
}
$cli = Get-HarnessProperty $documents.cli 'cli'
$node = Get-HarnessProperty (Get-HarnessProperty $documents.node 'node') $Platform
$pty = Get-HarnessProperty (Get-HarnessProperty $documents.pty 'pty') $Platform
if (-not $cli) { throw "The CLI manifest ($($sources.cli)) has no 'cli' entry." }
if (-not $node) { throw "The Node runtime manifest ($($sources.node)) has no '$Platform' entry: Harness is not published for this computer yet." }
if (-not $pty) { throw "The terminal host manifest ($($sources.pty)) has no '$Platform' entry: Harness is not published for this computer yet." }
return @{
cli = @{ entry = $cli; source = $sources.cli }
node = @{ entry = $node; source = $sources.node }
pty = @{ entry = $pty; source = $sources.pty }
}
}
function Get-HarnessSha256([string]$Path) {
# A file's SHA-256 as lowercase hex, computed by .NET. Not Get-FileHash: in Windows PowerShell 5.1 that is a script
# function which module autoload has to find, and a PSModulePath handed on by PowerShell 7 (a pwsh 7 window, CI)
# makes autoload load 7's Microsoft.PowerShell.Utility instead, where it does not exist: "The term 'Get-FileHash'
# is not recognized" (CI run 38826134075). Every other command here is a compiled cmdlet 5.1 has from the start.
$stream = [IO.File]::OpenRead((Get-Item -LiteralPath $Path).FullName)
try {
$sha = [Security.Cryptography.SHA256]::Create()
try { return [BitConverter]::ToString($sha.ComputeHash($stream)).Replace('-', '').ToLowerInvariant() } finally { $sha.Dispose() }
} finally { $stream.Dispose() }
}
function Save-HarnessVerified {
# Download (or copy, for a local manifest), then keep the file only if its size and SHA-256 are the manifest's.
# The manifest is the trust: the downloaded bytes are not, until they match it.
param([string]$Source, [string]$Destination, [string]$Sha256, $Size)
if ($Sha256 -notmatch '^[0-9a-fA-F]{64}$') { throw "The manifest gives no valid SHA-256 for $Source." }
try {
if (Test-HarnessUrl $Source) {
Invoke-HarnessRetry { Invoke-WebRequest -Uri $Source -OutFile $Destination -UseBasicParsing -TimeoutSec 600 } | Out-Null
} elseif (Test-HarnessScheme $Source) {
throw "Only https:// addresses are trusted, and $Source is not one."
} else {
Copy-Item -LiteralPath $Source -Destination $Destination -Force
}
$length = (Get-Item -LiteralPath $Destination).Length
if ($null -ne $Size -and "$Size" -ne '' -and [int64]$Size -ne $length) {
throw "$Source is $length bytes, but the manifest says ${Size}: the download is incomplete, or is not the published file."
}
$got = Get-HarnessSha256 $Destination
if ($got -ne $Sha256.ToLowerInvariant()) { throw "$Source failed its checksum (expected $Sha256, got $got): it is not the published file." }
} catch {
Remove-Item -LiteralPath $Destination -Force -ErrorAction SilentlyContinue
throw
}
}
function Expand-HarnessZip {
# Unpack the archive into the destination; the archive is moved there first and removed afterwards. tar.exe reads
# its arguments in the ANSI code page, so a profile path with a letter outside it (a CJK name on a Western
# Windows) reached it as '?' and the archive could not be opened (seen on the VM, 2026-10-16). It therefore runs
# inside the destination, on an ASCII relative name: a native command's working directory is PowerShell's current
# location, and is handed over in Unicode.
param([string]$Tar, [string]$Archive, [string]$Destination)
New-Item -ItemType Directory -Force -Path $Destination | Out-Null
$name = ".harness-archive-$PID.zip"
$local = Join-Path $Destination $name
Move-Item -LiteralPath $Archive -Destination $local
Push-Location -LiteralPath $Destination
try {
& $Tar -xf $name
$code = $LASTEXITCODE
} finally {
Pop-Location
Remove-Item -LiteralPath $local -Force -ErrorAction SilentlyContinue
}
if ($code -ne 0) { throw "Could not unpack $Archive (tar.exe exit code $code)." }
}
function New-HarnessStaging {
# The name the CLI's own sweep recognizes (.<name>-staging-<pid>-<time>, runtimeInstall.ts sweepStaging).
# A folder left by an installer that was stopped is removed by the next daemon start.
param([string]$Parent, [string]$Name)
$dir = Join-Path $Parent ".$Name-staging-$PID-$([DateTime]::UtcNow.Ticks)"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
return $dir
}
function Move-HarnessFile {
# Rename over the destination, retried. An antivirus scan or the search indexer can hold a new file for a
# moment, and a harness-launch.exe that is still exiting holds its own. The backup name is [NullString]::Value:
# Windows PowerShell 5.1 passes a plain $null to a .NET string as "", which Replace rejects ("The path is not
# of a legal form"), so every pointer that already existed failed to update (seen on the VM, 2026-10-16).
param([string]$Source, [string]$Destination)
for ($i = 1; ; $i++) {
try {
if ([IO.File]::Exists($Destination)) { [IO.File]::Replace($Source, $Destination, [NullString]::Value) } else { [IO.File]::Move($Source, $Destination) }
return
} catch {
if ($i -ge 5) { Remove-Item -LiteralPath $Source -Force -ErrorAction SilentlyContinue; throw }
Start-Sleep -Milliseconds (50 * $i)
}
}
}
function Test-HarnessSameFile([string]$Source, [string]$Destination) {
if (-not (Test-Path -LiteralPath $Destination -PathType Leaf)) { return $false }
if ((Get-Item -LiteralPath $Source).Length -ne (Get-Item -LiteralPath $Destination).Length) { return $false }
return (Get-HarnessSha256 $Source) -eq (Get-HarnessSha256 $Destination)
}
function Copy-HarnessFile {
# Copy through a temporary file and a rename, and only when the bytes differ: a file that is already right is left
# alone. A program that is running (a `harness` someone left open) can be renamed but not deleted. Replace then
# renames it to <name>~RF<hex>.TMP itself and succeeds (seen on the VM, 2026-10-16); should it fail instead, the
# program is moved aside to .<name>.old-<pid>-<time>. Remove-HarnessAside deletes either once it has exited.
param([string]$Source, [string]$Destination)
if (Test-HarnessSameFile $Source $Destination) { return }
$temp = "$Destination.tmp-$PID"
Copy-Item -LiteralPath $Source -Destination $temp -Force
try {
Move-HarnessFile -Source $temp -Destination $Destination
} catch {
if (-not [IO.File]::Exists($Destination)) { throw }
$aside = Join-Path (Split-Path -Parent $Destination) (".{0}.old-{1}-{2}" -f (Split-Path -Leaf $Destination), $PID, [DateTime]::UtcNow.Ticks)
[IO.File]::Move($Destination, $aside)
Copy-Item -LiteralPath $Source -Destination $temp -Force
Move-HarnessFile -Source $temp -Destination $Destination
}
}
function Remove-HarnessAside([string]$Dir) {
# The programs Copy-HarnessFile moved aside. One that still runs cannot be deleted yet, and waits for the next run.
foreach ($pattern in '.*.old-*', '*~RF*.TMP') {
Get-ChildItem -LiteralPath $Dir -Filter $pattern -Force -ErrorAction SilentlyContinue | Remove-Item -Force -ErrorAction SilentlyContinue
}
}
function Write-HarnessPointer {
# One line and CRLF, UTF-8 with no BOM, through a rename (installLayout.ts writePointer). The Rust reader
# (pty/src/launcher.rs, which harness.exe and harness-launch.exe use) would keep a BOM as part of the value.
param([string]$Path, [string]$Value)
$temp = "$Path.tmp-$PID"
[IO.File]::WriteAllText($temp, "$Value`r`n", (New-Object Text.UTF8Encoding $false))
Move-HarnessFile -Source $temp -Destination $Path
}
function Add-HarnessUserPath {
# Add the folder to the user's PATH in HKCU\Environment once. The value keeps its kind (REG_EXPAND_SZ, normally)
# and every entry already in it. An entry is compared expanded, case-insensitively and without a trailing
# backslash, so %USERPROFILE%\.harness\bin counts as the same folder. With no -SubKey it is Environment, or
# HARNESS_INSTALL_ENV_KEY when that is set: a test that forgets -SubKey still never writes the real PATH.
param([string]$Directory, [string]$SubKey)
if (-not $SubKey) { $SubKey = if ($env:HARNESS_INSTALL_ENV_KEY) { $env:HARNESS_INSTALL_ENV_KEY } else { 'Environment' } }
$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey($SubKey)
try {
$current = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
$kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
if ($current -ne '') { try { $kind = $key.GetValueKind('Path') } catch { } }
$entries = @($current -split ';' | Where-Object { $_ -ne '' })
$wanted = $Directory.TrimEnd('\')
foreach ($entry in $entries) {
if ([Environment]::ExpandEnvironmentVariables($entry).TrimEnd('\') -ieq $wanted) { return $false }
}
$key.SetValue('Path', ((@($entries) + $wanted) -join ';'), $kind)
return $true
} finally { $key.Close() }
}
function Send-HarnessEnvironmentChange {
# Tell Explorer, and through it every terminal started from now on, that the user's PATH changed. Add-Type
# compiles a little C#, which Constrained Language Mode (some managed computers) forbids. That only means a
# new terminal must be opened from a fresh Explorer, so it is a note and not a failure.
try {
if (-not ('Harness.NativeMethods' -as [type])) {
Add-Type -Namespace Harness -Name NativeMethods -MemberDefinition @'
[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wParam, string lParam, uint fuFlags, uint uTimeout, out UIntPtr lpdwResult);
'@
}
$result = [UIntPtr]::Zero
[void][Harness.NativeMethods]::SendMessageTimeout([IntPtr]0xffff, 0x1A, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$result)
} catch {
Write-Host ' (Could not announce the PATH change; terminals opened after you sign in again will see it.)'
}
}
# --- Install ---
function Test-HarnessPtyFolder([string]$Dir) {
foreach ($name in $HarnessPtyFiles) { if (-not (Test-Path -LiteralPath (Join-Path $Dir $name) -PathType Leaf)) { return $false } }
return $true
}
function Install-HarnessNode {
# runtime\node-<version>-<platform>\node.exe, from nodejs.org's own zip (node-<version>-win-<arch>\node.exe).
# current-node is written last, and only once node.exe has answered. The CLI, the desktop app and harness.exe
# all execute what it names.
param([string]$Root, $Entry, [string]$Source, [string]$Tar, [string]$Platform)
$version = [string]$Entry.version
if ($version -notmatch '^v\d+\.\d+\.\d+$') { throw "The Node runtime manifest names an unexpected version '$version'." }
$archiveRoot = [string]$Entry.archiveRoot
if ($archiveRoot -notmatch '^node-v\d+\.\d+\.\d+-win-(x64|arm64)$') { throw "The Node runtime manifest names an unexpected archive folder '$archiveRoot'." }
$runtime = Join-Path $Root 'runtime'
New-Item -ItemType Directory -Force -Path $runtime | Out-Null
$target = Join-Path $runtime "node-$version-$Platform"
$node = Join-Path $target 'node.exe'
if (-not (Test-Path -LiteralPath $node -PathType Leaf)) {
Write-Host " Downloading Node $version ($Platform)..."
$staging = New-HarnessStaging $runtime 'node'
try {
$archive = Join-Path $staging 'node.zip'
Save-HarnessVerified -Source (Resolve-HarnessRef ([string]$Entry.url) $Source) -Destination $archive -Sha256 ([string]$Entry.sha256) -Size $Entry.size
Expand-HarnessZip -Tar $Tar -Archive $archive -Destination $staging
$unpacked = Join-Path $staging $archiveRoot
if (-not (Test-Path -LiteralPath (Join-Path $unpacked 'node.exe') -PathType Leaf)) { throw "The Node archive has no $archiveRoot\node.exe." }
# A folder without node.exe is what a stopped install leaves; nothing can be running from it.
if (Test-Path -LiteralPath $target) { Remove-Item -LiteralPath $target -Recurse -Force }
Move-Item -LiteralPath $unpacked -Destination $target
} finally { Remove-Item -LiteralPath $staging -Recurse -Force -ErrorAction SilentlyContinue }
}
$said = & $node --version
if ($LASTEXITCODE -ne 0) { throw "The Node runtime at $node does not run on this computer." }
Write-HarnessPointer -Path (Join-Path $runtime 'current-node') -Value $node
Write-Host " OK Node $said -> $target"
}
function Install-HarnessCli {
# cli\<version>\cli.js, notify.mjs and package.json, written into staging and renamed into place, then
# cli\current and the stable cli\notify.mjs. A version folder whose cli.js already has the manifest's digest
# is kept: it is that version, and a running daemon may be using it.
param([string]$Root, $Entry, [string]$Source)
$version = [string]$Entry.version
if ($version -notmatch $HarnessCliVersionPattern) { throw "The CLI manifest names an unexpected version '$version'." }
foreach ($part in 'cli', 'notify') { if (-not (Get-HarnessProperty $Entry $part)) { throw "The CLI manifest has no '$part' file." } }
$cliRoot = Join-Path $Root 'cli'
New-Item -ItemType Directory -Force -Path $cliRoot | Out-Null
$target = Join-Path $cliRoot $version
$installed = Join-Path $target 'cli.js'
$current = (Test-Path -LiteralPath $installed -PathType Leaf) -and (Test-Path -LiteralPath (Join-Path $target 'notify.mjs') -PathType Leaf) -and ((Get-HarnessSha256 $installed) -ieq [string]$Entry.cli.sha256)
if (-not $current) {
Write-Host " Downloading Harness $version..."
$staging = New-HarnessStaging $cliRoot 'cli'
try {
Save-HarnessVerified -Source (Resolve-HarnessRef ([string]$Entry.cli.url) $Source) -Destination (Join-Path $staging 'cli.js') -Sha256 ([string]$Entry.cli.sha256) -Size $Entry.cli.size
Save-HarnessVerified -Source (Resolve-HarnessRef ([string]$Entry.notify.url) $Source) -Destination (Join-Path $staging 'notify.mjs') -Sha256 ([string]$Entry.notify.sha256) -Size $Entry.notify.size
# The bundle is an ES module, and Node decides that from the nearest package.json. install.sh writes the same file.
[IO.File]::WriteAllText((Join-Path $staging 'package.json'), "{""type"":""module""}`n", (New-Object Text.UTF8Encoding $false))
if (Test-Path -LiteralPath $target) { Remove-Item -LiteralPath $target -Recurse -Force }
Move-Item -LiteralPath $staging -Destination $target
} finally { if (Test-Path -LiteralPath $staging) { Remove-Item -LiteralPath $staging -Recurse -Force -ErrorAction SilentlyContinue } }
}
Write-HarnessPointer -Path (Join-Path $cliRoot 'current') -Value $version
Copy-HarnessFile -Source (Join-Path $target 'notify.mjs') -Destination (Join-Path $cliRoot 'notify.mjs')
Write-Host " OK Harness $version -> $target"
return $version
}
function Install-HarnessPty {
# runtime\pty\<version>\ with the host, the launcher, the harness command, ConPTY and harness-serial (the dial's
# port, sub-project E), then current-pty and
# bin\harness-launch.exe. A complete version folder is never replaced: a host may be running from it, and a running
# .exe cannot be overwritten on Windows (A's spec, host upgrade). It returns the version folder.
param([string]$Root, $Entry, [string]$Source, [string]$Tar)
$version = [string]$Entry.version
if ($version -notmatch $HarnessPtyVersionPattern) { throw "The terminal host manifest names an unexpected version '$version'." }
$ptyRoot = Join-Path $Root 'runtime\pty'
New-Item -ItemType Directory -Force -Path $ptyRoot | Out-Null
$target = Join-Path $ptyRoot $version
if (-not (Test-HarnessPtyFolder $target)) {
Write-Host " Downloading the terminal host $version..."
$staging = New-HarnessStaging $ptyRoot 'pty'
try {
$archive = Join-Path $staging 'pty.zip'
Save-HarnessVerified -Source (Resolve-HarnessRef ([string]$Entry.url) $Source) -Destination $archive -Sha256 ([string]$Entry.sha256) -Size $Entry.size
$unpacked = Join-Path $staging 'payload'
Expand-HarnessZip -Tar $Tar -Archive $archive -Destination $unpacked
if (-not (Test-HarnessPtyFolder $unpacked)) { throw "The terminal host archive lacks one of $($HarnessPtyFiles -join ', ')." }
if (Test-Path -LiteralPath $target) { Remove-Item -LiteralPath $target -Recurse -Force }
Move-Item -LiteralPath $unpacked -Destination $target
} finally { Remove-Item -LiteralPath $staging -Recurse -Force -ErrorAction SilentlyContinue }
}
$pointer = Join-Path $ptyRoot 'current-pty'
$before = ''
if (Test-Path -LiteralPath $pointer -PathType Leaf) { $before = ([string](Get-Content -LiteralPath $pointer -TotalCount 1)).Trim() }
Write-HarnessPointer -Path $pointer -Value $version
# An explicit install supersedes a host the updater put on probation: left, its marker would let the next probation
# roll this install back to the version before it (pty-pending.json, cli/src/lib/windows/ptyInstall.ts).
if ($before -ne $version) { Remove-Item -LiteralPath (Join-Path $ptyRoot 'pty-pending.json') -Force -ErrorAction SilentlyContinue }
$bin = Join-Path $Root 'bin'
New-Item -ItemType Directory -Force -Path $bin | Out-Null
Copy-HarnessFile -Source (Join-Path $target 'harness-launch.exe') -Destination (Join-Path $bin 'harness-launch.exe')
Write-Host " OK terminal host $version -> $target"
return $target
}
function Install-HarnessCommand {
# bin\harness.exe, the `harness` command (pty/src/command.rs), from the terminal host's version folder. It holds
# no path itself: it finds the install from its own folder and reads the two pointers the installer and the
# updater keep, so Node and the CLI can move on without it. It is a program and not a batch file, so cmd never
# parses the arguments a second time. A harness.cmd that an earlier install wrote goes: it re-parsed them.
param([string]$Root, [string]$PtyFolder)
$bin = Join-Path $Root 'bin'
New-Item -ItemType Directory -Force -Path $bin | Out-Null
$command = Join-Path $bin 'harness.exe'
Copy-HarnessFile -Source (Join-Path $PtyFolder 'harness.exe') -Destination $command
# The same program as `hn`: by that name it is `harness tui` (pty/src/command.rs).
Copy-HarnessFile -Source (Join-Path $PtyFolder 'harness.exe') -Destination (Join-Path $bin 'hn.exe')
$old = Join-Path $bin 'harness.cmd'
if (Test-Path -LiteralPath $old) { Remove-Item -LiteralPath $old -Force }
Remove-HarnessAside $bin
return $command
}
function Add-HarnessPath {
# The user's PATH for every new terminal, and this session's own PATH so `harness` works in this window now.
# Under `irm | iex` that is the person's own session. HARNESS_INSTALL_ENV_KEY (tests only) moves the registry
# write to a throwaway key and skips the broadcast.
param([string]$Root)
$bin = Join-Path $Root 'bin'
$subKey = 'Environment'
if ($env:HARNESS_INSTALL_ENV_KEY) { $subKey = $env:HARNESS_INSTALL_ENV_KEY }
if (Add-HarnessUserPath -Directory $bin -SubKey $subKey) {
if (-not $env:HARNESS_INSTALL_ENV_KEY) { Send-HarnessEnvironmentChange }
Write-Host " OK added $bin to your PATH"
}
if (-not (@($env:Path -split ';') | Where-Object { $_.TrimEnd('\') -ieq $bin })) { $env:Path = "$env:Path;$bin" }
}
function Register-HarnessService {
# The task that starts Harness at sign-in and keeps it running (harness service install, sub-project B3). A
# computer whose policy forbids user tasks still has a working Harness, so a failure here is a sentence and
# not a failed install.
param([string]$Command)
$exit = 1
$why = ''
try {
& $Command service install | ForEach-Object { Write-Host " $_" }
$exit = $LASTEXITCODE
} catch { $why = $_.Exception.Message }
# 5: the task is registered, and Task Scheduler did not start harnessd now, as over SSH
# (serviceCommand.ts SERVICE_REGISTERED_NOT_RUNNING). It said "could not set itself to start" of a task it had just
# registered (the Windows install job, B5.12). harness service install has said what happened and what to run; this
# adds nothing to it (re-review N1).
if ($exit -eq 5 -and -not $why) { return }
if ($exit -ne 0) {
if (-not $why) { $why = "harness service install exited $exit" }
Write-Host " Harness could not set itself to start when you sign in ($why)."
Write-Host " It still works: run 'harness start' to connect this computer."
return
}
try { & $Command status | ForEach-Object { Write-Host " $_" } } catch { }
}
function Test-HarnessReady {
# Signed in, and the daemon running: then the closing guide has no setup steps to give (G8, a reinstall over a live
# install said "1. sign in"). Anything it cannot read counts as not ready, and the steps are given.
# The CLI's stderr (a sign-in refresh warning, say) is dropped, never part of the closing text. Continue here: with
# Stop, Windows PowerShell 5.1 turns a native command's redirected stderr line into a terminating error.
# The status row's glyph is optional: Windows PowerShell may read it in the console code page as other characters.
param([string]$Command)
if (-not $Command) { return $false }
$ErrorActionPreference = 'Continue'
try {
$auth = (@(& $Command auth status --json 2>$null) -join "`n") | ConvertFrom-Json
if ($LASTEXITCODE -ne 0 -or $auth.loggedIn -ne $true) { return $false }
$line = @(& $Command status 2>$null) | Where-Object { $_ -match '^\s*status\s' } | Select-Object -First 1
return [bool]($LASTEXITCODE -eq 0 -and $line -match '^\s*status\s+(\S+\s+)?(running|started)\b')
} catch { return $false }
}
function Write-HarnessDone {
param([string]$Version, [switch]$Desktop, [switch]$NoService, [string]$Command)
Write-Host ''
if ($Desktop) { Write-Host " harness $Version installed."; return }
Write-Host " OK harness $Version installed."
Write-Host ''
if (Test-HarnessReady -Command $Command) {
Write-Host ' This computer is signed in and Harness is running: nothing more to set up.'
Write-Host ''
Write-Host ' Useful:'
Write-Host ' harness status # is the daemon running, and which machine this is'
Write-Host ' harness remote-password set # let your OTHER machines reach this one, if you have not yet'
Write-Host ' harness --help # everything else'
Write-Host ''
Write-Host ' harness works in this window now. Terminals that were already open see it once they are reopened.'
return
}
Write-Host ' Set this computer up with three commands, in this order:'
Write-Host ''
Write-Host ' harness login # 1. sign in with your Autonomous account (opens a browser)'
Write-Host ' harness start # 2. connect this computer as a machine (runs in the background)'
Write-Host ' harness remote-password set # 3. let your OTHER machines reach this one (asked once, kept)'
Write-Host ''
Write-Host ' Useful:'
Write-Host ' harness status # is the daemon running, and which machine this is'
Write-Host ' harness --help # everything else'
Write-Host ''
Write-Host ' harness works in this window now. Terminals that were already open see it once they are reopened.'
}
function Find-HarnessGit {
# The git Store installs clone with, or '' when this computer has none. Windows does not come with one, and git
# was missing on computers where every Store install failed at once (0 of 25 in three days, 2026-10-28). PATH
# first, then where Git for Windows installs, for everyone or for this user alone, in case PATH is not updated yet.
param(
[string]$Path = $env:PATH,
[string[]]$Roots = @($env:ProgramFiles, ${env:ProgramFiles(x86)}, $(if ($env:LOCALAPPDATA) { Join-Path $env:LOCALAPPDATA 'Programs' }))
)
foreach ($dir in ($Path -split ';')) {
$git = Get-HarnessFileIn -Folder $dir -Name 'git.exe'
if ($git) { return $git }
}
foreach ($root in $Roots) {
$git = Get-HarnessFileIn -Folder $root -Name 'Git\cmd\git.exe'
if ($git) { return $git }
}
return ''
}
function Get-HarnessFileIn {
# [Folder]\[Name] when that file exists, else ''. Joined as text and tried on its own: PATH can name a drive that is
# not there (an unplugged USB disk, an unmapped share), where Join-Path stops with 'Cannot find drive', or hold an
# entry in quotes, which .NET calls illegal. Under the installer's errors-stop either one turned a finished install
# into a failed one (review of #2025).
param([string]$Folder, [string]$Name)
if (-not $Folder) { return '' }
try {
$file = [IO.Path]::Combine($Folder, $Name)
if (Test-Path -LiteralPath $file -PathType Leaf) { return $file }
} catch { }
return ''
}
function Write-HarnessGitNote {
# Said, not done: installing Git for Windows is the person's choice, and this installer changes nothing outside
# their own folder and PATH. Harness itself runs without git; the Store's harnesses do not.
param([string]$Git = (Find-HarnessGit))
if ($Git) { return }
Write-Host ''
Write-Host ' Git for Windows is not installed. Harnesses from the Store are installed with git, and run their setup in its Git Bash.' -ForegroundColor Yellow
Write-Host ' Install it, then open a new window:'
Write-Host ''
Write-Host ' winget install --id Git.Git -e'
Write-Host ''
Write-Host ' or download it from https://git-scm.com/download/win'
}
function Read-HarnessCurrentCli {
# The version cli\current names, or '' before a first install.
param([string]$Root)
$pointer = Join-Path $Root 'cli\current'
if (-not (Test-Path -LiteralPath $pointer -PathType Leaf)) { return '' }
return ([string](Get-Content -LiteralPath $pointer -TotalCount 1)).Trim()
}
function Read-HarnessCurrentPty {
# The version runtime\pty\current-pty names, or '' before a first install. Read before the payload install moves
# it, so Restart-HarnessDaemon can tell that only the terminal host changed.
param([string]$Root)
$pointer = Join-Path $Root 'runtime\pty\current-pty'
if (-not (Test-Path -LiteralPath $pointer -PathType Leaf)) { return '' }
return ([string](Get-Content -LiteralPath $pointer -TotalCount 1)).Trim()
}
function Restart-HarnessDaemon {
# Run again over a live install, the installer moves the daemon to the new build. The master re-execs only before
# a core starts, and nothing tells it that cli\current moved, so the daemon is restarted once: harness stop, then
# harness start. Agents keep running: the terminal host is independent of the daemon, and the new core reattaches
# them. It also restarts when only the terminal host moved: a daemon holds on to the host it started with, so a new
# host is used only after a restart. Nothing happens when neither version changed, on a first install, or when no
# daemon runs. An explicit install installs: pty-rejected.json is the updater's back-off and is not read here.
param([string]$Command, [string]$Before, [string]$After, [string]$PtyBefore, [string]$PtyAfter)
$cliMoved = $Before -and $Before -ne $After
$ptyMoved = $PtyBefore -and $PtyBefore -ne $PtyAfter
if (-not $cliMoved -and -not $ptyMoved) { return $false }
$statusLine = @(& $Command status) | Where-Object { $_ -match '^\s*status\s' } | Select-Object -First 1
if ($LASTEXITCODE -ne 0 -or -not $statusLine -or $statusLine -match 'stopped|out of reach') { return $false }
if ($cliMoved) {
Write-Host " Moving the running Harness from $Before to $After (your agents keep running)..."
} else {
Write-Host " Moving the running Harness to terminal host $PtyAfter (your agents keep running)..."
}
& $Command stop | ForEach-Object { Write-Host " $_" }
# A daemon that did not stop is still on the old build: nothing is started beside it, and no move is reported.
if ($LASTEXITCODE -ne 0) {
if ($cliMoved) {
Write-Host " Harness is still running version $Before; it moves to $After when it next restarts (harness stop, then harness start)."
} else {
Write-Host " Harness is still running on terminal host $PtyBefore; it moves to $PtyAfter when it next restarts (harness stop, then harness start)."
}
return $false
}
# Not piped, and not left as the function's output (which a caller's `$null =` would capture through a pipe too):
# the daemon `harness start` leaves running inherits the handles that command writes to, and a pipe read here would
# not end until the daemon did (seen on the VM). Start-Process -NoNewWindow gives it this window's own, and waits
# for that one process only. Reading Handle first keeps ExitCode readable once it has exited.
$start = Start-Process -FilePath $Command -ArgumentList 'start' -NoNewWindow -PassThru
$null = $start.Handle
$start.WaitForExit()
if ($start.ExitCode -ne 0) {
if ($cliMoved) { Write-Host " Harness did not start again on version ${After}. Run 'harness start'." }
else { Write-Host " Harness did not start again on terminal host ${PtyAfter}. Run 'harness start'." }
}
return $true
}
function Install-Harness {
# install.sh's steps, in its order. Each step is named, so a failure says which one in a sentence a first-time
# user can act on. Nothing outside %USERPROFILE%\.harness and the user's PATH is ever changed.
param([switch]$Desktop, [string]$Manifest, [switch]$NoService)
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue' # Windows PowerShell 5.1 downloads many times slower with the bar drawn
$root = Join-Path $env:USERPROFILE '.harness'
$step = 'Checking this computer'
try {
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
$tar = Test-HarnessHost
$platform = Get-HarnessPlatform
Write-Host "Installing Harness for $platform into $root"
$step = 'Reading the release manifests'
$sources = Get-HarnessManifests -Manifest $Manifest -Platform $platform
$step = 'Installing the Node runtime'
Install-HarnessNode -Root $root -Entry $sources.node.entry -Source $sources.node.source -Tar $tar -Platform $platform
$step = 'Installing the Harness CLI'
# The version a running daemon may be on, read before the pointer moves (Restart-HarnessDaemon below).
$before = Read-HarnessCurrentCli -Root $root
$ptyBefore = Read-HarnessCurrentPty -Root $root
$version = Install-HarnessCli -Root $root -Entry $sources.cli.entry -Source $sources.cli.source
# The terminal host is installed in -Desktop mode too: the daemon the app starts runs its terminals on it.
$step = 'Installing the terminal host'
$ptyFolder = Install-HarnessPty -Root $root -Entry $sources.pty.entry -Source $sources.pty.source -Tar $tar
$step = 'Installing the harness command'
$ptyAfter = Split-Path -Leaf $ptyFolder
$command = Install-HarnessCommand -Root $root -PtyFolder $ptyFolder
$step = 'Adding Harness to your PATH'
Add-HarnessPath -Root $root
$step = 'Checking the installed CLI'
$said = [string](@(& $command version) | Select-Object -First 1)
if ($LASTEXITCODE -ne 0 -or $said.Trim() -ne $version) { throw "harness version answered '$said' (exit code $LASTEXITCODE), not $version." }
$step = 'Moving the running Harness to the new build'
# $null: Install-Harness returns a single integer (the guard takes the last value).
$null = Restart-HarnessDaemon -Command $command -Before $before -After $version -PtyBefore $ptyBefore -PtyAfter $ptyAfter
if (-not $Desktop -and -not $NoService) {
$step = 'Starting Harness when you sign in'
Register-HarnessService -Command $command
}
} catch {
Write-Host ''
Write-Host "Harness could not be installed. The step that failed: $step." -ForegroundColor Red
Write-Host " $($_.Exception.Message)" -ForegroundColor Red
Write-Host " Nothing outside $root and your PATH was changed. Run the installer again, or send this message to Harness support."
return 1
}
Write-HarnessDone -Version $version -Desktop:$Desktop -NoService:$NoService -Command $command
Write-HarnessGitNote
return 0
}
function ConvertTo-HarnessVersionKey([string]$Version) {
# C4.7 publishes X.Y.Z or X.Y.Z-prerelease. Only the three numeric parts order, as in DesktopUpdater.
if (-not ($Version -cmatch '^([0-9]+)\.([0-9]+)\.([0-9]+)(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$')) { return $null }
try { return [version]::new([int]$Matches[1], [int]$Matches[2], [int]$Matches[3]) }
catch { return $null } # A published-looking component outside [version]'s range cannot order.
}
function Select-HarnessAppEntry {
# Native x64 uses x64. Native arm64 takes the newer arm64 or x64 entry, with arm64 winning a tie.
param($Document, [string]$Platform)
$keys = if ($Platform -eq 'win32-arm64') { @('desktop-windows-arm64', 'desktop-windows-x64') } else { @('desktop-windows-x64') }
$best = $null
foreach ($key in $keys) {
$entry = Get-HarnessProperty $Document $key
$value = Get-HarnessProperty $entry 'version'
$url = Get-HarnessProperty $entry 'url'
$sha256 = Get-HarnessProperty $entry 'sha256'
$size = Get-HarnessProperty $entry 'size'
if ($value -isnot [string] -or $url -isnot [string] -or $sha256 -isnot [string] -or
($size -isnot [int] -and $size -isnot [long])) { continue }
$version = ConvertTo-HarnessVersionKey $value
if ($version -and (-not $best -or $version -gt $best.version)) { $best = @{ entry = $entry; version = $version } }
}
if (-not $best) { throw "The desktop manifest has no Harness desktop app for this computer ($Platform) yet." }
return $best.entry
}
function Start-HarnessAppInstall {
# Wait for the extracted Harness.exe --install alone. The installed app it opens keeps running.
param([string]$Launcher)
$info = [Diagnostics.ProcessStartInfo]::new($Launcher, '--install')
$info.UseShellExecute = $false
$info.WorkingDirectory = Split-Path -Parent $Launcher
$process = [Diagnostics.Process]::Start($info)
try {
$process.WaitForExit()
return $process.ExitCode
} finally { $process.Dispose() }
}
function Install-HarnessApp {
# Download the complete desktop zip, verify it, and let its own launcher install and open it.
param([string]$Manifest)
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$step = 'Checking this computer'
$staging = $null
$installed = $false
try {
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
$tar = Test-HarnessHost
$platform = Get-HarnessPlatform
$step = 'Reading the release manifest'
$source = "${HarnessManifestBase}desktop/metadata.json"
if ($Manifest) {
$source = $Manifest
if (-not (Test-HarnessUrl $source) -and -not (Test-HarnessScheme $source)) {
if (-not (Test-Path -LiteralPath $source -PathType Leaf)) { throw "The manifest $source does not exist." }
$source = (Resolve-Path -LiteralPath $source).ProviderPath
}
}
$entry = Select-HarnessAppEntry -Document (Get-HarnessJson $source) -Platform $platform
$version = [string]$entry.version
Write-Host "Installing the Harness desktop app $version for $platform"
$step = 'Downloading Harness'
$staging = New-HarnessStaging -Parent ([IO.Path]::GetTempPath()) -Name 'harness-desktop'
$zip = Join-Path $staging 'harness-desktop.zip'
Save-HarnessVerified -Source (Resolve-HarnessRef -Ref ([string]$entry.url) -ManifestSource $source) -Destination $zip -Sha256 ([string]$entry.sha256) -Size $entry.size
$step = 'Unpacking Harness'
$folder = Join-Path $staging 'zip'
Expand-HarnessZip -Tar $tar -Archive $zip -Destination $folder
$launcher = Join-Path $folder 'Harness.exe'
if (-not (Test-Path -LiteralPath $launcher -PathType Leaf)) { throw 'The download has no Harness.exe, so it is not a Harness desktop app.' }
$step = 'Installing Harness'
$code = Start-HarnessAppInstall -Launcher $launcher
if ($code -ne 0) { throw "Harness's installer stopped (exit code $code). Its log is launch.log, in Programs\Harness under $env:LOCALAPPDATA." }
$installed = $true
} catch {
Write-Host ''
Write-Host "Harness could not be installed. The step that failed: $step." -ForegroundColor Red
Write-Host " $($_.Exception.Message)" -ForegroundColor Red
Write-Host ' Run the installer again, or send this message to Harness support.'
return 1
} finally {
if ($staging) {
try { Remove-Item -LiteralPath $staging -Recurse -Force -ErrorAction Stop }
catch {
Write-Host "Warning: Temporary files remain at $staging." -ForegroundColor Yellow
if ($installed) { Write-Host ' Harness was installed and can be used.' }
else { Write-Host ' The install failed for the reason above.' }
Write-Host " Close anything using that folder, then remove it. $($_.Exception.Message)"
}
}
}
Write-Host ''
Write-Host "Harness $version is installed, and it is opening now."
Write-Host 'Next time, open it from the Start menu. On its first start it sets up the Harness command line.'
Write-HarnessGitNote
return 0
}
# --- Run ---
if ($env:HARNESS_INSTALL_LIBRARY -ne '1') {
if (-not $Manifest) { $Manifest = $env:HARNESS_INSTALL_MANIFEST }
if ($App -or $HarnessInstallApp) {
$harnessExit = @(Install-HarnessApp -Manifest $Manifest)[-1]
} else {
$harnessExit = @(Install-Harness -Desktop:([bool]$Desktop) -Manifest $Manifest -NoService:([bool]$NoService))[-1]
}
# Run as a file, the exit code is the result. Run by `irm | iex`, it never calls `exit`: that would close the
# person's PowerShell window with the message still in it.
if ($HarnessScriptPath) { exit $harnessExit }
$global:LASTEXITCODE = $harnessExit
}