Distribution, installation and offline use

SPART-Desk ships as one npm package, and the package is the installation: nothing is downloaded, cached or provisioned beside it. The Windows backend is SPART-Desk's own helper executable, native/spart-desk-host.exe, which ships inside the package, signed.

npm package (~2.2 MB)
  engine + the spart-desk command
  native/spart-desk-host.exe (~390 KB, signed in releases)   ← the Windows backend
  native/spart-desk-host-x86.exe (~390 KB, signed)           ← its 32-bit build, for 32-bit Java runtimes and 32-bit windows
  no models, no artifact cache

The helper reads every window through Windows UI Automation and acts on what it read, sends real input, takes pictures, reads the process table, reads text with the recognizer built into Windows, talks to the Java Access Bridge, and runs inside the Windows Sandbox guest (experimental) as the engine's agent there. It runs on the .NET Framework that every Windows 10 and 11 installation has, so it needs nothing installed. The engine never starts PowerShell. On machines with application control (WDAC, AppLocker, Smart App Control) or a strict antivirus, allow the signed spart-desk-host.exe by publisher; npx spart-desk doctor reports whether it runs and whether it is signed. What each gate does with the helper is on windows-security-gates.md. See backend-windows.md.

What a machine needs

Tier	Needs	What works
core	Node 24	The locator model, assertions, diagnostics, the fake backend (@spartaficial/spart-desk/testing), the agent package against fakes. Installs and type-checks on any OS.
core+windows	+ Windows 10 1809 or later, Windows 11 or Windows Server 2025 (Desktop Experience), with the helper running	Everything above plus real applications through UI Automation, native input, screenshots, Windows Sandbox (experimental; Windows 11 24H2+), reading text off the screen and matching a picture.

That second line is the whole installation story: the package. Reading text uses the recognizer built into Windows through the helper, and matching a picture is the engine's own correlation, so neither adds a download, a model or a cache entry. One package is opt-in and carries what it needs in its own npm tarball, so an npm mirror carries it offline like any other package: @spartaficial/spart-desk-ocr-paddle, for applications the Windows recognizer misreads, holds PaddleOCR's models (37 MB, pinned by SHA-256) and ONNX Runtime's native build for Windows x64 and Arm64 (59 MB, Microsoft's signed files).

npx spart-desk doctor prints the capability map of the current machine: uia, java, nativeInput, screenshot, text, imageMatch, elements, grounding (experimental), each either available or carrying the reason it is not. Everything but elements and grounding rests on the helper: where it cannot run, each says so, with what would allow it. What is missing fails explicitly, never silently: the first action on a machine whose helper is missing or blocked fails at once with BackendError helper_unavailable, and anything else raises CapabilityUnavailableError naming the ability, the reason and what would enable it. Grounding (getByVision) has no bundled provider at all and is enabled by passing one.

Installing

npm install @spartaficial/spart-desk
npx spart-desk init         # spart-desk.config.ts and an example test
npx spart-desk doctor       # what this machine can do, capability by capability

That is all of it. The helper lies in the package at node_modules/@spartaficial/spart-desk/native/spart-desk-host.exe, beside dist/, and the engine finds it there; doctor starts it once (version and session) and reports the path, whether it runs, and the session as the helper reads it (locked, remote, not interactive).

Air-gapped machines

Mirror the npm registry (Artifactory, Nexus, Verdaccio) or carry the tarballs: on a connected machine, npm pack @spartaficial/spart-desk (and, where they are used, npm pack @spartaficial/spart-desk-agent and npm pack @spartaficial/spart-desk-ocr-paddle) writes <name>-<version>.tgz, and npm install ./spartaficial-spart-desk-<version>.tgz installs it on the other side. Nothing else has to cross the air gap: no artifact bundle, no mirror of anything but packages, no proxy setting of SPART-Desk's own. Pin the package through your lockfile as usual.

The helper's signature

The helper in the published package is signed by Spartaficial with Azure Artifact Signing (formerly Trusted Signing), in the release pipeline and never on a workstation. Application control policies therefore allow spart-desk-host.exe (and spart-desk-host-x86.exe, signed the same way) by publisher; the file's properties name the company (Spartaficial), the product (SPART-Desk) and the package's version. doctor prints signature signed by …, or invalid (0x…) for a file changed after signing (reinstall the package). What SmartScreen, Smart App Control, WDAC, AppLocker and Defender each do with the helper, and the administrator's rules, are on windows-security-gates.md.

The spart-desk command

npx spart-desk doctor [--json]
npx spart-desk version [--json]

Command	Purpose
doctor	The platform (OS and Windows build, architecture, Node, supported or not: Windows 10 1809 and later; whether it is Windows Server), the helper (its path, the package version it was built for, whether it starts and answers, whether it is signed and by whom, the session as it reads it), wsb.exe for the sandbox runtime (experimental) and where the guest's files are staged, the Java runtimes JAVA_HOME and PATH point at (each with whether it carries the Java Access Bridge), the resulting tier (core, or core+windows when the helper runs), the capability map, and actionable problems. Exit 1 when the tier is core and problems exist.
version	The package's version.

The same report is available programmatically from @spartaficial/spart-desk/install: doctor (→ DoctorReport, with HelperStatus, JavaRuntimeStatus, CapabilityTier), defaultCacheDir, ENV and the PATH finders (findOnPath, findWsbOnPath, presentSync), so a provisioning check needs no shell.

The one folder SPART-Desk keeps

Experimental

The Windows Sandbox runtime may change in minor versions until its prerequisites are validated against a live Windows Sandbox.

SPART_DESK_CACHE_DIR names the one place the engine keeps files of its own: %LOCALAPPDATA%\spart-desk on Windows by default ($XDG_CACHE_HOME/spart-desk or ~/.cache/spart-desk elsewhere). Today it holds only the Windows Sandbox runtime's staging folders (sandbox\<id>: the helper, the agent's material and the launched applications' folders, shared into the guest read-only; runtime-windows-sandbox.md). doctor prints it, and it can be deleted at any time.

Package boundaries

The core package keeps its name and stays code-only but for the helper. The agent layer remains the separate @spartaficial/spart-desk-agent package (different dependencies and consumers), and the engine is a peer dependency of it so that a consumer resolves exactly one copy.

Troubleshooting

Symptom	Meaning / fix
doctor says the helper cannot run, or BackendError [helper_unavailable]	spart-desk-host.exe is missing from the installation (an antivirus may have quarantined it), or an application control policy (Smart App Control, WDAC, AppLocker) blocks it. Reinstall the package, or allow the signed file by publisher (windows-security-gates.md).
BackendError [helper_protocol]	The helper beside the engine is from another build. Reinstall @spartaficial/spart-desk so that native/spart-desk-host.exe matches it.
CapabilityUnavailableError	Something was asked for that this desktop cannot do. The error names the ability, why it is missing and what would enable it.