Client agent: operations and rollout

For administrators. As of September 2026 (Server 1.0.31, Agent 1.0.36). Related guides: Administration Handbook (chapter "Connecting clients"), Quick Admin Guide (step by step with screenshots), Devices without a domain (API key), Known issues, Distributing MSIX packages, Policies and templates.

1. What is this?

The ZeroPortal client agent runs on the end device. It asks the portal what is assigned to the computer and to the signed-in user, and puts that into effect locally: MSIX packages (also as App Attach), App-V packages and connection groups, and ZeroPortal policies. It tells the portal that the device and user are active (licence receipt), and shows the user through a tray icon what is happening right now.

Signing in to the portal. On a domain, the agent needs no configuration: the service signs in with the computer account (Kerberos), the user sync with the user's ticket. Devices without a domain fetch a key of their own through an enrollment token (stored protected under HKLM\SOFTWARE\NickIT\ZPAgent\Auth); if a key exists, it is used, otherwise Kerberos. See Devices without a domain (API key).

2. What is this good for?

• Workstations on the domain. MSI through group policy or software deployment, every setting from one GPO. After the first sign-in the assigned applications appear; new assignments arrive with the next sync.
• Terminal servers and session hosts. The machine sync deploys packages machine-wide, the user sync registers them at every sign-in. App Attach keeps package content on one central image instead of in every profile.
• Notebooks. Without contact to the portal, the agent keeps working from its cache and removes nothing. Locally installed MSIX and fully loaded App-V packages run offline; App Attach needs the share.
• Several sites. A site-local path for the package source (MSIX/MSIXPackageRoot) keeps package traffic inside the site network.
• Clusters. Several portal servers in the server list form a priority chain; on a failure, the agent switches to the next one.
• Devices without Active Directory. Pilot devices or standalone machines sign in with a key they fetch themselves using an enrollment token.

3. How do I use this?

3.1 Getting the agent MSI

The agent MSI matching the server is in the portal's sidebar under Download (full administrators, and groups with level Read for the Download area on the Permissions page). New agent versions arrive with the server update.

Edge and SmartScreen warn about a rarely downloaded file: Keep and Keep anyway. For regular downloads, exempt the portal's domain by policy (section 3.2).

3.2 Preparing the browser: intranet zone and SmartScreen

Intranet zone. For the browser and the agent to sign in via Kerberos without a login window, the portal URL belongs in the Local Intranet zone. A login window despite correct permissions is almost always this missing zone mapping (missing permissions show up as "no access"). By GPO: User Configuration → Administrative Templates → Windows Components → Internet Explorer → Internet Control Panel → Security Page → Site to Zone Assignment List, portal FQDN with value 1; this also applies to Edge and Chrome. An SPN is only needed if the portal is reached under an alias name (Known issues).

SmartScreen. GPO Computer Configuration → Administrative Templates → Microsoft Edge → SmartScreen settings → Configure the list of domains for which Microsoft Defender SmartScreen won't trigger warnings (registry: HKLM\SOFTWARE\Policies\Microsoft\Edge\SmartScreenAllowListDomains, value 1 = portal FQDN). If Edge reports "unsafe download blocked", the portal was opened over HTTP instead of HTTPS.

3.3 Preparing group policy (ADMX)

Where do I find the ADMX template? It is installed with the agent and sits on every device with the agent under

C:\Program Files\NickIT\ZeroPortalAgent\admx

The folder holds ZeroPortalAgent.admx and the language folders de-DE and en-US with the matching .adml files. There is no separate download: install the agent once on any machine (the portal server works too) and take the files from there.

Copy the files into your domain's central store (\\<domain>\SYSVOL\<domain>\Policies\PolicyDefinitions). The settings then appear under Computer Configuration → Administrative Templates → NickIT → ZeroPortal Agent.

Four settings decide everything else. They sit directly in the ZeroPortal Agent folder; all others are in the subfolders.

After installation, all three sync areas are off: the agent connects to the portal but delivers nothing. Turn on only what you really need.

Keep App-V sync off when the Microsoft App-V client fetches the packages. There are two ways to do App-V, and only one may be active on a device. Either the Microsoft App-V client queries the portal itself as its publishing server — then Enable App-V sync stays off. Or the ZeroPortal agent handles the App-V packages — then enter no publishing server in the Microsoft client. If both run, they publish and remove the same packages in turn: shortcuts disappear and come back, and the log entries chase each other. MSIX and policies are not affected; they may run side by side.

With your own PKI, distribute the portal's server certificate with the same GPO into the computer's Trusted Root Certification Authorities store; the service runs as System and does not see user certificates.

3.4 Installing the agent

msiexec /i ZeroPortalAgent-<Version>.msi /qn

The service starts right away, the first machine sync runs about 30 seconds later, and the tray icon appears in every signed-in session. No restart is needed.

You only need MSI parameters if you work without group policy (test, workgroup):

Upgrade. A newer MSI installs over the existing version; the service and tray restart in the process. For a big version jump, or if an upgrade rolls back with error 1603: uninstall the old version, then install the new MSI. Avoid series of installs and service restarts minutes apart (section 5.2).

3.5 First check

On the client, in an administrative PowerShell session:

Get-ZPAgentStatus                 # service reachable, version, server list
Get-ZPAgentSync                   # which areas are on, and where the value comes from
Sync-ZPAgentPublishingServer      # trigger a sync right now
Get-ZPAgentPackage                # packages managed by the agent

The user sees the same in the tray icon: Sync now, Show packages…, Open logs, Deployment times…, and Settings… (central settings take precedence).

After the first sync, the device appears in the portal on the Global Configuration → Agent enrollment page, on the Known clients card.

3.6 Changing settings

The rule of thumb: what the agent needs to start comes from group policy. How it behaves in operation comes from a policy in the portal.

Group policy offers 25 settings, the portal policy reaches all 57 switches. Only group policy has the publishing servers and the enrollment token — the agent needs both before it can reach a portal at all. Conversely, 34 switches have no entry in the template, among them the App Attach mount path, the rules for removal, downgrade and self-healing, and the tray behaviour; set those through the portal policy or locally. Appendix 6.1: if the ADMX column names a setting, it also works by group policy.

1. Group policy (ADMX) for the server list, failover, timing, the three sync switches, and logging. Always wins.
2. ZeroPortal policy of type Agent configuration in the portal (template Agent configuration, see Policies and templates): reaches every switch in the catalogue. Takes effect at the next sync; a value later removed from the policy is reset on the device.
3. PowerShell, locally, with Set-ZPAgentConfiguration -<switch> <value>; every switch is its own parameter, and tab completion lists them all:

Get-ZPAgentConfiguration                                 # all switches: name, value, SetByGroupPolicy, area
Get-ZPAgentConfiguration -SyncIntervalMinutes            # just this switch
Set-ZPAgentConfiguration -SyncIntervalMinutes 30
Set-ZPAgentConfiguration -LogLevel Debug
Enable-ZPAgentSync -Msix -Policy                         # turn sync areas on locally

3.7 Publishing servers without group policy

Add-ZPAgentPublishingServer -Name 'ZeroPortal' -Url 'https://portal:8443'
Get-ZPAgentPublishingServer
Remove-ZPAgentPublishingServer -Name 'ZeroPortal'

The local list only applies while no GPO list is configured; once the GPO applies, the local list is ignored (not deleted).

3.8 Changing the App Attach mount path

MSIX/AppAttachMountRoot sets where App Attach images (VHDX/CIM) are mounted; empty means C:\ProgramData\NickIT\AppAttach. If the path is unusable (drive missing), the agent falls back to the default (event 3535). A change remounts every App Attach package under the new path at the next sync and registers it again — so do it in a maintenance window: Set-ZPAgentConfiguration -AppAttachMountRoot 'D:\AppAttach' (or the Agent configuration policy), Stop-Service ZeroPortalAgent, restart. Mounts do not survive a restart; the agent clears out empty folders of the old path at startup.

3.9 Site-local package source

MSIX/MSIXPackageRoot (ADMX: Package source root override) replaces the prefix \\server\share of the catalogue URL with a local path or DFS path; the rest of the path stays. Applies to MSIX bits and App Attach images. If a package is missing there, the agent loads it from the original source.

4. Rules: when does what apply

4.1 Order of precedence for settings

When reading settings: group policy before the Agent configuration policy before the local value (PowerShell, MSI parameters) before the built-in default. If a switch is set by GPO, Set-ZPAgentConfiguration and Enable-ZPAgentSync have no visible effect; Get-ZPAgentConfiguration shows this in the SetByGroupPolicy column.

4.2 Timing

A new interval applies after the next run; Periodic user sync, Log level, and Alternative log path at the next service start or user sync.

4.3 Server list and failover

• The GPO list is authoritative. After a change: gpupdate /force on the client; the agent reads the list at the next sync (or right away with Sync-ZPAgentPublishingServer).
• Failover (default): the list is a priority chain of identical replicas. The first server to answer within the failover timeout counts as the complete view; the cleanup run follows its catalogue. Only servers with the same catalogue belong in one list.
• Merge-all (failover off): every server is contacted and the content is merged. Only for independent portals. If one does not answer, the cleanup run is skipped (event 3500), so no package from a failed server gets removed.
• Random server selection spreads the load: per run, the agent starts at a random server from the list.
• A server that answers with an error (403, 500) counts as reachable and does not land on the blacklist; the agent tries the next one.

4.4 Removal, downgrade, format switch

• Nothing is removed without server contact. If a fetch fails, everything stays as it is.
• A package missing from the catalogue is removed at the next sync (MSIX/AutoUninstallOnUnpublish; MSIX/ManagedPackageMissThreshold = number of syncs it must be missing for). MSIX/GlobalRemovalPolicy: Immediate right away, WhenIdle and OnReboot mark it and remove it later or at the next service start, Disabled only watches. If the application is running, removal is deferred (MSIX/DeferRemovalWhileInUse), and happens at the latest after MSIX/RemovalIdleTimeoutHours (24).
• Downgrade is off (MSIX/AllowDowngrade): a newer local version counts as satisfied (event 2538 or 3510). A Package downgrade control policy per package family takes precedence (Distributing MSIX packages).
• Format switch MSIX ↔ App Attach: the agent closes the running application and registers the package again (MSIX/TerminateAppsForFormatSwitch); off = the switch waits while it runs (event 3544).
• Turning a sync area off (MSIX, App-V, policies) leaves what was already delivered unchanged.
• Sweep of orphaned shortcuts: Agent/ShortcutSweepMode Off (default), ZeroPortal (own packages only), All (all local ones).

4.5 Offline: notebooks and mobile devices

Practical rule: mobile devices get MSIX or fully loaded App-V, not App Attach.

• Policies stay at the last applied state (offline cache, event 3600); an entry is only taken back when a reachable server reports that it is gone.
• Licence: the receipt lasts 90 days and is renewed once 28 days remain. Notices such as "no licence free" only follow a real server answer, at most every 4 hours. Only when the receipt has expired and the portal stays unreachable does the user see a notice; the applications keep running either way.
• Back online, the first successful sync catches up on everything: packages, policies, licence renewal.

5. Operations and troubleshooting

5.1 Logs

The agent writes only to these text files, not to the Windows event log. Every line carries a timestamp, a level (INF, WRN, ERR), and the event ID in square brackets (appendix 6.4); each sync ends with a summary of counters and the names of failed packages.

• Detailed diagnostics: Set-ZPAgentConfiguration -LogLevel Debug (or GPO Log level), applies at the next service start or user sync; set it back to Information afterwards.
• A different location: Agent/LogPath (GPO Alternative log path). The service and the user must be able to write there, otherwise the respective log is silently dropped.
• Clear-ZPAgentLog deletes all agent logs; there is no automatic rotation.
• The user reaches the folder through Open logs in the tray menu; Deployment times… shows how long packages and policies took (Agent/DeploymentReport).
• The ADMX setting Do not write user names to the agent log (folder Privacy) is not evaluated yet in this version.

5.2 Running it stably and finding faults

Every service start remounts all App Attach images and runs a full sync. Installs, uninstalls, or service restarts minutes apart cause mount/unmount churn in which modern apps (Task Manager, Start menu) can crash at launch — temporarily, with no lasting damage. So: after an install, wait for the first sync; while testing, stop the service between changes (Stop-Service ZeroPortalAgent) instead of quickly restarting it; on test devices with many App Attach packages, throttle the periodic sync (Agent/MachineSyncPeriodicEnabled=0 or a larger MSIX/SyncIntervalMinutes). If it happens: stop the service, restart the device.

6. Appendix: technical reference

6.1 Switches

The switches an administrator typically changes. Settable by GPO (column "ADMX"), by the Agent configuration policy, or locally with Set-ZPAgentConfiguration -<switch> <value>. Get-ZPAgentConfiguration on the device gives the full list with current values; every switch is a parameter of Set-ZPAgentConfiguration.

6.2 Registry

Three roots: GPO = HKLM\SOFTWARE\Policies\NickIT\ZPAgent (wins when read; the agent reads every catalogue key here, even ones without an ADMX entry), Local = HKLM\SOFTWARE\NickIT\ZPAgent (PowerShell, MSI parameters, Agent configuration policy), User = HKCU\SOFTWARE\NickIT\ZPAgent.

The tray icon has no autostart entry under Run; the service starts it (Agent/TrayAutostart). Values set by ZeroPortal policies (drives, registry, shortcuts …) live at their respective targets, not under ZPAgent.

6.3 Cmdlets of the ZeroPortalAgent module

6.4 Event IDs in the agent log (selection)