For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installation & Update

This page explains how the desktop agent installs and updates itself on Windows and macOS — what runs, in what order, where files land, and how updates are triggered and applied. It is a reference for IT/security teams who need to understand the moving parts behind the step-by-step deployment guides.

There are two flavours of the agent:

  • Standard (MyZenV2) — visible, interactive app.

  • Stealth (zs) — headless. A background service monitor (svcmonitor) supervises the tracker, applies admin commands, and performs updates.

Both flavours share the same Go tooling and the same per-tenant key configuration (zs.json, the tenant id + key the installer is bound to).


Windows — installation

Primary path: self-contained installer (zs-setup.exe)

The recommended installer is a single self-contained executable with the entire application payload embedded inside it, so it installs fully offline with no download step.

  1. Resolve the tenant key config. The installer determines which tenant it belongs to from (in order) an installer-sources.json beside it, an installer text marker, the executable's own (encoded) filename, or an existing C:\Windows\System32\zs.json.

  2. Elevate to administrator (UAC prompt if not already elevated).

  3. Write the key config to the canonical path C:\Windows\System32\zs.json so the agent and service always read the current tenant binding (this happens on update/repair too, replacing a stale config).

  4. Extract & validate the payload, with a short settle delay so antivirus can inspect files before they're used.

  5. Place files atomically with rollback (stage .new, move current to .old, rename into place; restore on failure) — resilient to AV locks/quarantine.

  6. Register and start the Windows service (svcmonitor) with crash-recovery, write install registry keys, and add outbound firewall rules.

Legacy path: MSI (Advanced Installer)

An MSI (zs.msi / MyZenV2.msi) is still produced for enterprise deployment via Group Policy / SCCM / Intune. It lays down the same file layout and service. New deployments should prefer the self-contained zs-setup.exe for offline/air-gapped scenarios. (The configure_user.exe helper is no longer shipped in either path — onboarding now runs in-process in the app.)

Windows services

Service
Role

svcmonitor (C:\Windows\svcmonitor.exe)

Supervises the tracker, polls the server for admin commands, performs updates, ships logs on request. Auto-start, with sc failure crash recovery.

svcrunner (C:\Windows\svcrunner.exe)

Companion that keeps svcmonitor alive across sessions/crashes.


macOS — installation

The agent ships as a signed, notarized .pkg, built per architecture (amd64 and arm64 — no universal binary, intentionally). Gatekeeper acceptance, stapling, and signature integrity are verified at build time.

The package installs the app bundle and runs a postinstall script that:

  1. Stops any existing app/processes.

  2. Resolves and writes the tenant key config to /Library/Preferences/zs.json (stealth uses a keyconfig_check helper that reads the tenant from the package's own name).

  3. Renders launchd job definitions from templates and bootstraps them for the system and logged-in GUI users.

launchd jobs

Job
Flavour
Type
Purpose

ai.we360.MyZenV2

Standard

LaunchAgent (per user)

Starts the interactive app at login

ai.we360.MyZenV2-updater

Standard

LaunchDaemon (system)

Hourly update check

ai.zs.zs

Stealth

LaunchAgent/Daemon

Starts/keeps svcmonitor running

ai.zs.zs-updater

Stealth

LaunchDaemon (system)

Runs svcmonitor updater to check/apply updates


File locations

Windows
macOS

Stealth app

C:\Program Files\zs\zs\

/usr/local/zs/zs.app

Standard app

C:\Program Files\… (MSI)

/Applications/MyZenV2.app

Service binaries

C:\Windows\svcmonitor.exe, svcrunner.exe

inside the app bundle (…/Contents/MacOS/svcmonitor), run via launchd

Tenant key config

C:\Windows\System32\zs.json (fallback …\zs\zs\keyconfig.json)

/Library/Preferences/zs.json (fallback /etc/zs.json)

Version file

…\zs\zs\version.txt

…/Contents/MacOS/version.txt

Per-user config (tokens)

%APPDATA%\ai.zs\zs.ini

~/.config/ai.zs/zs.ini

App data / logs

%APPDATA%\ai.zs\zs\

~/Library/Application Support/ai.zs/zs

A custom key-config path can be supplied via the ZS_KEY_CONFIG environment variable (used by always-on mode); it overrides the platform default path.


Updates

Updates are server-led and per-tenant, with a build-time fallback URL. The agent never auto-downgrades by accident.

Agent update flow

The updater begins with the installed version and returns to that current state after every check, whether it applies a newer release or leaves the installation unchanged.

In short, policy and version gates produce a safe no-op when an update is not eligible, integrity failure aborts before installation, and a successful apply—or the documented Windows rollback—returns the agent to an installed current version.

Process stage
What is observable
What causes progression
Operator action

Installed / current version

The installed version is recorded in version.txt.

An hourly or timer-based check, or an on-demand UPDATE command for the stealth agent.

None for scheduled checks; an administrator can issue UPDATE for an on-demand stealth check.

Policy and version gates

The tenant response supplies auto_update and the latest version; a local skip marker can hold the update.

Updates continue only when they are allowed and the published version is higher.

No action is required; the configured policy or hold determines whether the installation remains unchanged.

Download and integrity verification

No separate administrator-facing status is documented; the package MD5 is checked against the published .version sidecar.

A match starts installation; a mismatch aborts it.

No operator procedure is specified on this page.

Applying the update

Windows reruns its installer or MSI; macOS installs the per-architecture package system-wide.

Successful installation makes the applied version current.

No action is required during the automatic apply.

Integrity failure

Installation is aborted and the installed version remains unchanged.

A later scheduled or requested check starts the flow again.

No operator procedure is specified on this page.

Windows apply failure / rollback

If the atomic file swap fails, the installer restores the previous Windows files.

Restoration returns the device to its previous installed version.

Rollback is automatic; no separate action is documented.

How an update is decided

  1. Resolve the installer URL for this tenant: GET https://origin.in.we360.ai/discover/v1/tenant/<id>/download-urls/ (cached in-process). If unavailable, fall back to the per-brand build-time base URL.

  2. Check the auto-update gate (auto_update per tenant). If disabled, the updater no-ops.

  3. Compare versions with a strict semver gate — an update installs only when the published version is higher than the installed one. (Intentional rollbacks require publishing a new build with the older bits.)

  4. Verify integrity — the download's MD5 is checked against the published .version sidecar; a mismatch aborts the install.

How an update is applied

  • Windows: svcmonitor re-runs the self-contained zs-setup.exe (downloaded for this tenant), which stops the service, performs the same atomic file swap as a fresh install, and recreates/starts the service. MSI assets are applied via msiexec /i … /qn /norestart.

  • macOS: the *-updater launchd job runs the updater, which downloads the per-arch .pkg and installs it system-wide via /usr/sbin/installer -pkg … -target /. The stealth updater encodes the tenant key config into the package path so postinstall can re-bind the tenant.

Cadence & triggers

  • Standard (macOS): hourly via the updater LaunchDaemon.

  • Stealth (both OS): svcmonitor checks on a timer (only while a user session is active) and also honours an on-demand UPDATE admin command delivered through the service-state channel.

  • Skip markers: developer/opt-out markers on disk cause the updater to no-op (used for dev machines and temporary holds).


  • Step-by-step install guides: Manual Installation (Windows/macOS, standard/stealth).

  • Mass deployment: Mass Deployment (GPO, Intune, MDM, command-line MSI).

  • Network behaviour & endpoints: Network & Security Hardening → Stealth App — Server Communication (v4.13+).

Last updated

Was this helpful?