Sotero Runtime Windows Installation and Developer Setup Guide

Before you begin

What the installer adds

The MSI installs a self-contained daemon, developer resources, a machine PATH entry, and the native SoteroDaemon Windows Service. On a fresh installation, it securely generates the required 32-byte signing secret inside sotero-daemon, writes the protected service configuration under C:\ProgramData\Sotero, registers the service for automatic startup, and starts it. The service runs as LocalSystem with a service-scoped USERPROFILE that points to C:\ProgramData\Sotero.

Requirements

• Windows 10 or 11, or Windows Server 2019 or later, on an x86_64 operating system.
• A Windows account that can approve a User Account Control elevation prompt.
• Administrator access to approve the installer UAC prompt and perform service lifecycle commands.
• The official MSI and, when supplied, its matching SHA-256 checksum sidecar.
• Local access to TCP port 5100. The default listener is loopback-only and is not exposed to the network.

[Environment]::Is64BitOperatingSystem
[Environment]::OSVersion.Version
$PSVersionTable.PSVersion

Download Sotero Runtime

1. Open the Download link from the site navigation and sign in with Google, Microsoft, or your Sotero email and password.
2. Review and accept the required End User License Agreement. Separate marketing consent is optional.
3. Choose Windows x86_64 and download sotero-runtime-0.0.2-windows-x86_64.msi and its checksum when available.

Verify the Windows package

cd $env:USERPROFILE\Downloads
$msi = ".\sotero-runtime-0.0.2-windows-x86_64.msi"

Get-FileHash -Algorithm SHA256 $msi
Get-AuthenticodeSignature $msi |
    Format-List Status, StatusMessage, SignerCertificate

If no checksum sidecar was supplied, obtain the expected SHA-256 value from your release administrator. Do not disable SmartScreen or signature checking to install a package whose origin cannot be verified.

Install with Windows Installer

Use this method for a normal interactive installation. A regular File Explorer or PowerShell session is sufficient to launch the MSI; Windows Installer requests administrator approval through UAC when it performs per-machine changes.

1. Open Downloads in File Explorer and double-click the verified MSI.
2. Approve the User Account Control prompt. If you cannot approve it, ask a Windows administrator to install the package.
3. Review the installation screen and continue with the default destination under Program Files.
4. Wait for the successful completion message, then close the installer. The MSI creates the service configuration and starts SoteroDaemon automatically.
5. Open a new PowerShell window so the updated machine PATH is visible.

How service configuration is handled

The service does not use C:\Users\<you>\.sotero. It runs as LocalSystem with USERPROFILE=C:\ProgramData\Sotero, so its authoritative configuration is C:\ProgramData\Sotero\.sotero\sotero.toml. The MSI creates this configuration on a fresh installation and restricts access to SYSTEM and Administrators.

Verify the background service

The installer has already started the service. Wait briefly, then confirm Windows Service Control Manager reports Running and verify both liveness and readiness. Readiness checks the registry, catalog, signing store, replay store, and Control authentication — not only whether a process exists.

Start-Sleep -Seconds 8

Get-Service SoteroDaemon
& "C:\Program Files\Sotero Runtime\sotero-daemon.exe" service status
Invoke-RestMethod "http://127.0.0.1:5100/healthz"
Invoke-RestMethod "http://127.0.0.1:5100/readyz"

Verify the service profile registration

reg.exe query `
    "HKLM\SYSTEM\CurrentControlSet\Services\SoteroDaemon" `
    /v Environment

# Expected value:
# USERPROFILE=C:\ProgramData\Sotero

Verify restart behavior

Restart-Service SoteroDaemon
Start-Sleep -Seconds 8
& "C:\Program Files\Sotero Runtime\sotero-daemon.exe" service status

Service lifecycle commands

Status and HTTP health checks can be performed from a regular PowerShell window. Start, stop, restart, registration changes, and ProgramData writes require Administrator PowerShell.

Use Sotero Runtime as a developer

Connect through local TCP

Windows uses TCP loopback at 127.0.0.1:5100. The default bind is local to the machine. Copy the packaged thin client into an importable location in your Python project.

Copy-Item "C:\Program Files\Sotero Runtime\thin-client.py" `
    ".\sotero_thin_client.py"
python -m pip install "httpx>=0.27" "PyJWT[crypto]>=2.8" "cryptography>=42"

from sotero_thin_client import ThinClientRuntime

runtime = ThinClientRuntime()
runtime.onboard(daemon_url="http://127.0.0.1:5100")

When Control API authentication is required, provide the secret through your application's approved secret-management mechanism. Do not hard-code it.

Install the bundled Claude Code skills

& "C:\Program Files\Sotero Runtime\sotero-daemon.exe" install-skills
# Default destination: %USERPROFILE%\.claude\skills

Run skill installation as your normal user, not as Administrator, so the files are placed in your own profile. Restart Claude Code if it was already running.

Useful operator commands

Configuration and file reference

When changes take effect

• Changes to sotero.toml require Restart-Service SoteroDaemon.
• The configured agents file and Rego policy file are watched and hot-reloaded.
• When sotero.toml and a matching environment variable both contain a value, the file value wins.
• Variables exported in your own PowerShell session are not inherited by LocalSystem.
• Keep signing_key_secret stable while encrypted state exists. Restore the original secret rather than replacing it on a production instance.

Logs and troubleshooting

Audit events and startup diagnostics

The logs command reads audit decisions, not service startup stderr. Windows SCM does not capture the daemon's console output in a normal text file. To read the service audit log with the CLI, temporarily use the service's USERPROFILE in the current Administrator PowerShell process.

$originalUserProfile = $env:USERPROFILE
$env:USERPROFILE = "C:\ProgramData\Sotero"
try {
    & "C:\Program Files\Sotero Runtime\sotero-daemon.exe" `
        --config "C:\ProgramData\Sotero\.sotero\sotero.toml" `
        logs --last 100
} finally {
    $env:USERPROFILE = $originalUserProfile
}

For a service that starts and immediately stops, obtain debug-windows-service.ps1 from Sotero support or the source operations bundle. It captures a ProgramData-profile foreground reproduction, service state, health checks, executable signature, and relevant Windows events without copying configuration contents or secret values.

Set-ExecutionPolicy -Scope Process Bypass
cd C:\path\to\diagnostic-script
.\debug-windows-service.ps1

# The timestamped folder and ZIP are created beside the script.

Common symptoms

Reset disposable test state

Stop-Service SoteroDaemon -ErrorAction SilentlyContinue
$originalUserProfile = $env:USERPROFILE
$env:USERPROFILE = "C:\ProgramData\Sotero"
try {
    & "C:\Program Files\Sotero Runtime\sotero-daemon.exe" `
        --config "C:\ProgramData\Sotero\.sotero\sotero.toml" `
        reset-access --yes
} finally {
    $env:USERPROFILE = $originalUserProfile
}

Upgrade or replace Sotero Runtime

Upgrade to a newer version

1. Back up C:\ProgramData\Sotero\.sotero, especially sotero.toml, registry.db, keys.db, and audit.jsonl.
2. Download and verify the newer signed MSI and checksum.
3. Install the newer version interactively or with Administrator PowerShell. The MSI stops the old service, replaces product files, preserves ProgramData state, and starts the updated service.
4. Repeat the service-status, liveness, readiness, and restart checks.

Replace a rebuilt MSI with the same version

A rebuilt 0.0.2 MSI may have different contents but the same ProductVersion. Windows Installer does not reliably treat it as an upgrade. Uninstall the registered 0.0.2 product first, then install the rebuilt package. ProgramData state is preserved.

Stop-Service SoteroDaemon -Force -ErrorAction SilentlyContinue
Get-Process sotero-daemon -ErrorAction SilentlyContinue | Stop-Process -Force

$roots = @(
    "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
    "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
)
$product = Get-ItemProperty $roots -ErrorAction SilentlyContinue |
    Where-Object { $_.DisplayName -eq "Sotero Runtime" } |
    Select-Object -First 1

if ($product) {
    $remove = Start-Process msiexec.exe `
        -ArgumentList @("/x", $product.PSChildName, "/passive", "/norestart") `
        -Wait -PassThru
    $remove.ExitCode
}

After removal, install the rebuilt MSI with the earlier PowerShell procedure. Accept only exit code 0 or 3010, then repeat service-status, health, readiness, and restart verification. The preserved ProgramData configuration is reused automatically.

Uninstall Sotero Runtime

Standard uninstall

The standard uninstall removes installed product files and the SoteroDaemon service registration. It deliberately preserves C:\ProgramData\Sotero\.sotero so a future installation can resume with the same configuration and encrypted state.

1. Open Settings, choose Apps, then Installed apps.
2. Find Sotero Runtime and choose Uninstall.
3. Approve the UAC prompt and wait for removal to finish.

PowerShell uninstall with a verbose log

$roots = @(
    "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
    "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*"
)
$product = Get-ItemProperty $roots -ErrorAction SilentlyContinue |
    Where-Object { $_.DisplayName -eq "Sotero Runtime" } |
    Select-Object -First 1

if ($product) {
    $log = "$env:USERPROFILE\Desktop\sotero-uninstall.log"
    $remove = Start-Process msiexec.exe `
        -ArgumentList @(
            "/x", $product.PSChildName, "/passive", "/norestart",
            "/L*v", "`"$log`""
        ) -Wait -PassThru
    $remove.ExitCode
}

Verify removal

Test-Path "C:\Program Files\Sotero Runtime\sotero-daemon.exe"
Get-Service SoteroDaemon -ErrorAction SilentlyContinue

# Expected: False, followed by no service result.

Optionally remove all service data

Copy-Item -Recurse "C:\ProgramData\Sotero\.sotero" `
    "$env:USERPROFILE\Desktop\sotero-state-backup"

# Run only after verifying the backup and approving permanent deletion:
Remove-Item -Recurse -Force "C:\ProgramData\Sotero"

Quick reference

Expected steady state: SoteroDaemon is Running, the CLI reports supervisor RUNNING and health healthy, /healthz reports ok, and every /readyz check is true.