Skip to main content

Processing server as a Windows service

Install a persistent processing server on Windows.

Who this is for​

Use this path when you want to use a Windows machine as a remote Toposync processing server.

The script creates a Windows service named ToposyncProcessingServer.

For Windows architecture and GPU support, see Compatibility.

Prerequisites​

  • Windows 10/11.
  • PowerShell.
  • Administrator permission.
  • Internet access to GitHub, PyPI, and the uv installer.
  • Network access between the origin and the Windows machine.

The script installs uv and Python 3.12 if needed.

Installation​

Open PowerShell as Administrator.

Quick install without cloning the repository:

$script = Join-Path $env:TEMP 'install-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/install_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script -Bundle auto -Version latest -PreferLocalPackages:$false

The command downloads the installer to %TEMP% before running it. This keeps the installer able to reopen itself as Administrator if needed.

The auto mode chooses:

  • cuda, if it finds nvidia-smi;
  • directml, otherwise.

To force CPU, DirectML, CUDA, or a specific advertised IP, change the final installer arguments:

-Bundle cpu
-Bundle directml
-Bundle cuda
-AdvertiseHost 192.168.1.50

For development from a repository checkout, run the local script from the repository root:

powershell -ExecutionPolicy Bypass -File .\scripts\install_windows_processing_server.ps1 -Bundle auto -Version latest -PreferLocalPackages:$false -AdvertiseHost 192.168.1.50

How to run​

The script creates and starts the service automatically.

Check status:

Get-Service ToposyncProcessingServer

Restart:

Restart-Service ToposyncProcessingServer

Stop:

Stop-Service ToposyncProcessingServer

How to access​

By default, the service listens on:

http://<windows-ip>:49321

The script stores data in:

%ProgramData%\Toposync\ProcessingServer

The registration payload is saved at:

%ProgramData%\Toposync\ProcessingServer\processing-server-registration.json

How to verify​

View the registration JSON:

Get-Content "$env:ProgramData\Toposync\ProcessingServer\processing-server-registration.json"

If you installed with -NoAuth, test the local status:

Invoke-RestMethod -Uri http://127.0.0.1:49321/api/processing/status

By default, the script generates Basic Auth credentials. Use the username and password saved in the JSON:

$pair = "toposync:<password-from-json>"
$token = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
Invoke-RestMethod -Uri http://127.0.0.1:49321/api/processing/status -Headers @{ Authorization = "Basic $token" }

Register on the origin​

Use the payload saved at:

%ProgramData%\Toposync\ProcessingServer\processing-server-registration.json

The script also prints an Invoke-RestMethod example for registering the server on the origin.

Then validate through the origin:

Invoke-RestMethod http://ORIGIN_HOST:8000/api/processing-servers/<server-id>/status

In pipelines, set processing_server_id to the registered id.

How to update​

Run the installer again:

$script = Join-Path $env:TEMP 'install-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/install_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script -Bundle auto -Version latest -PreferLocalPackages:$false

To recreate the virtual environment:

$script = Join-Path $env:TEMP 'install-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/install_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script -Bundle auto -Version latest -PreferLocalPackages:$false -RecreateVenv

How to uninstall​

Remove the service and runtime files while preserving data and logs:

$script = Join-Path $env:TEMP 'uninstall-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/uninstall_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script

Also remove data and logs:

$script = Join-Path $env:TEMP 'uninstall-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/uninstall_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script -RemoveData

If the service is stuck:

$script = Join-Path $env:TEMP 'uninstall-toposync-processing.ps1'; Invoke-WebRequest 'https://raw.githubusercontent.com/toposync/toposync/main/scripts/uninstall_windows_processing_server.ps1' -OutFile $script; powershell -NoProfile -ExecutionPolicy Bypass -File $script -Force

Also remove the registered processing server from the origin.

Troubleshooting​

The service does not start​

Check the logs at:

%ProgramData%\Toposync\ProcessingServer\logs

Also check:

Get-Service ToposyncProcessingServer

Port is already in use​

The installer tries to choose the next free port when -AutoSelectPort is active. Check the final port in processing-server-registration.json.

The origin cannot connect​

Confirm the IP address in the JSON url, the selected port, and the firewall rule created by the installer.

Wrong bundle was selected​

Run the installer again with -Bundle cpu, -Bundle directml, or -Bundle cuda.