Windows Desktop Preview

DOCSight Desktop Preview for Windows

DOCSight Desktop Preview is a portable Windows build for trying DOCSight without Docker, WSL, PowerShell setup, or a server. It starts DOCSight locally and opens it in your browser.

Use it for first contact, demos, and short local tests. For reliable 24/7 monitoring, use the normal Docker deployment described in the Windows Quick Start.

Release status: Desktop Preview ZIPs are attached to published GitHub releases only. Each ZIP contains the same application code as that release (the stable image), so unreleased changes listed in the Roadmap are not part of the preview until they are released.

Choose the right Windows path

Goal	Recommended path
Try DOCSight quickly on a Windows PC	Desktop Preview ZIP
Explore Demo Mode, the setup wizard, Home, the glossary, or the evidence workflow	Desktop Preview ZIP
Monitor your line continuously on a machine that stays awake, or after host restarts	Docker Desktop on an always-awake Windows PC, or another always-on Docker host
Run DOCSight on a NAS, mini-PC, server, or homelab	Docker

Download and start

1. Open the latest DOCSight release.

2. Under Assets, download the unsigned portable Windows Desktop Preview ZIP. Its versioned name uses this shape:

   DOCSight-Desktop-Preview-win64-<version>.zip
   

3. Extract the ZIP to a folder such as Downloads\DOCSight or C:\Tools\DOCSight.

4. Start DOCSight.exe.

You do not need a GitHub account for this download path. PowerShell and checksum verification are optional.

Optional: verify download integrity

Each Windows Preview ZIP has a matching checksum asset named:

DOCSight-Desktop-Preview-win64-<version>.zip.sha256

For an optional integrity check, download that file from the same GitHub release. In PowerShell, run these commands from the folder where you saved both files:

$zip = ".\DOCSight-Desktop-Preview-win64-<version>.zip"
$checksumFile = "$zip.sha256"
$checksumText = Get-Content -LiteralPath $checksumFile -Raw
$expectedHash = if ([string]::IsNullOrWhiteSpace($checksumText)) { "" } else { ($checksumText.Trim() -split '\s+', 2)[0] }
$actualHash = (Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash
$checksumMatches = [string]::Equals($actualHash, $expectedHash, [System.StringComparison]::OrdinalIgnoreCase)
$checksumMatches

The final command returns True only when the ZIP hash matches the first hash value in the checksum file. SHA-256 is hexadecimal, so uppercase and lowercase letters represent the same hash value and are compared case-insensitively. A matching SHA256 checksum verifies download integrity against the published checksum. It does not verify publisher identity and does not replace a code signature.

First start and SmartScreen

The preview is a portable, unsigned app while signing provider onboarding is pending; see the code signing policy. Windows SmartScreen can therefore show an "unrecognized app" warning.

If you downloaded DOCSight from the official GitHub release and choose to continue, select More info and then Run anyway.

DOCSight starts a local web app and opens your default browser. The address is local to your PC, normally similar to:

http://127.0.0.1:8765

A small DOCSight startup window appears first. It shows the current local address with a Copy action from Start DOCSight onward and reports progress while it prepares local data, starts DOCSight, waits for readiness, and attempts to open the browser. After DOCSight is ready and the browser-open attempt succeeds, the startup window hides and a tray icon remains. Closing the browser does not exit DOCSight.

Double-click the tray icon, or select Open DOCSight, to reopen the exact active local address. The other menu actions are Open log folder and Quit. On a German Windows UI the labels are DOCSight öffnen, Log-Ordner öffnen, and Beenden; English is the fallback for other UI languages or when Windows language detection is unavailable.

The first successful tray start shows a one-time notification explaining this browser-versus-process behavior. Its marker is stored at %LOCALAPPDATA%\DOCSight\tray-notification-v1, so it is not shown on every launch.

Starting DOCSight.exe again reuses the already-running instance for the same Windows user. The later launcher waits for authenticated local readiness, opens the exact existing address, and exits without starting another server. This also works across multiple signed-in Windows sessions for the same account. Different Windows users keep separate instances and data.

If startup cannot finish or the browser cannot be opened, the window stays available instead of exiting silently. You can copy the displayed local address, choose Retry to start a fresh attempt, open the log folder, or close DOCSight. If native tray startup fails, this sanitized recovery surface stays visible rather than hiding the only controls. A browser-open failure does not mean the local app is unavailable: copy the address into a browser to continue.

Tray Quit uses one centralized shutdown path. It closes the local server, waits at most 12 seconds for application/startup and polling cleanup, stops the tray, and removes the runtime ownership record. If that bounded shutdown cannot finish, DOCSight logs only stable failure codes and exception class names and uses process exit code 1 as a last resort. Quit never launches a replacement.

What works in the Desktop Preview

The preview uses the same DOCSight web app as the matching release and is useful for exploring the product:

• Demo Mode.
• Initial setup wizard.
• Home and the signal views.
• Glossary and beginner help.
• Evidence Journey and local diagnostic exports.
• Basic supported-modem polling from your Windows PC.
• Connection Monitor with TCP-based checks.
• Local settings stored on your Windows user profile.

While the app runs in Desktop Preview mode, Home shows a dismissible Desktop Preview is a tryout build notice and a Desktop Preview badge that links to this page.

Known v0 limitations

Desktop Preview is intentionally not full Windows service support yet:

• Not an always-on monitor. It runs only while your Windows user session and the DOCSight process are running.
• Sleep and hibernate pause collection. If the laptop or PC sleeps, DOCSight cannot poll the modem or record connection samples during that time.
• No native ICMP probing in v0. Connection Monitor falls back to TCP probing on Windows. That still shows reachability signals, but it is not the same as raw ICMP ping.
• No Windows service or autostart setup. It does not install a background service that starts before login.
• No auto-update channel. Download a newer ZIP from GitHub releases when you want to update.
• No installer, MSIX, or Store package. The preview is a portable ZIP.
• Local-only browser app. It binds to loopback for tryout use, not to your LAN, so Windows does not ask for a firewall exception.

For continuous monitoring, use Docker on an always-on machine instead.

Where data lives

Desktop Preview stores its data under your Windows user profile:

%LOCALAPPDATA%\DOCSight

Typical subfolders:

Folder	Purpose
%LOCALAPPDATA%\DOCSight\data	Configuration and local monitoring database
%LOCALAPPDATA%\DOCSight\modules	Community modules and themes
%LOCALAPPDATA%\DOCSight\logs	Privacy-filtered launcher diagnostics in launcher.log; separate application diagnostics in runtime.log
%LOCALAPPDATA%\DOCSight\runtime.json	Versioned single-instance identity; replaced atomically and recovered after crashes

launcher.log contains only sanitized startup/recovery events and is intended to be shareable. runtime.log contains separate application diagnostics; review it before sharing because it can contain instance-specific operational details.

runtime.json contains the owning PID, selected loopback port, application version, process creation time, and a random per-run token. A launcher adopts that address only when the Windows process owner and creation time match and a token-authenticated loopback endpoint returns the same identity. Stale PIDs, reused PIDs, foreign listeners, malformed records, and ordinary /health responses are rejected. The record is not a LAN-access credential: the Desktop Preview remains bound only to 127.0.0.1.

The per-user mutex uses Windows' machine-visible Global\ namespace and is derived from the account SID, so it coordinates the same user across Windows sessions without sharing a server across users. If the direct token lookup fails, an independent process-token SID lookup establishes both the current owner identity and the same SID-derived mutex name. If both SID lookups fail, startup fails safely before mutex creation; the mutex name always remains SID-derived.

How release builds are checked

Linux test runs only enforce the static contract of the Windows release smoke test. The smoke test itself runs on a windows-latest runner when the Windows build workflow runs. It occupies the preferred port, races two launchers, requires one allowed fallback and exactly one IPv4 loopback listener owned by the validated runtime PID, and checks authenticated second/third launch handoff. It also requires runtime.log without packaged route/import degradation and deletes the first launcher's log before requiring fresh Prepare local data evidence from the injected recovery process. That recovery process must replace stale runtime state and expose a nonzero main-window handle with the title exactly DOCSight. Through a local sentinel enabled only with DOCSIGHT_SKIP_BROWSER=1, it also feeds the same quit command used by the tray. Two packaged open/setup/quit cycles must exit, close their selected ports, remove runtime state, leave no child or duplicate packaged process, reopen persisted setup, perform another write, and release the created data files.

This automation does not prove tray visibility or mouse/menu behavior; those remain explicit interactive Windows QA steps in the repository's Windows QA checklist. Packaging details are documented in packaging/windows/README.md.

Remove the Desktop Preview

1. Quit DOCSight from its tray icon.

2. Delete the extracted Desktop Preview folder.

3. If you also want to remove local data, delete:

   %LOCALAPPDATA%\DOCSight
   

Deleting the data folder removes configuration and history for the Desktop Preview.

Move from Desktop Preview to Docker

When you want DOCSight to monitor continuously:

1. Install Docker Desktop or use an always-on Docker host.

2. Follow the Windows Quick Start or the full Installation guide.

3. Start DOCSight with a persistent Docker volume:

   docker run -d --name docsight --restart unless-stopped -p 8765:8765 -v docsight_data:/data ghcr.io/itsdnns/docsight:stable

Docker remains the recommended path for 24/7 monitoring because it can restart with the host and is easier to run on a machine that stays online. To keep the history you collected in the preview, create a backup in the preview's Settings and restore it from the first-run page of the Docker instance; see Backup & Restore.