xg setup host

xg setup host

Advanced command. Installs or updates the Plugin Framework Host (XrmGhost.Framework.Host) — the component that xg run launches in the background to execute Dataverse plugins out-of-process — in the managed install root only. For first setup and repair, use xg init or xg doctor --fix.

Synopsis

xg setup host [OPTIONS]

When called without any option, setup host inspects the current installation state and prints a status message. It automatically performs an install if the Framework Host is missing from the expected location.

When you need it

If you installed the CLI with winget or from the -full.zip, the signed Framework Host is already bundled in the bin\ folder next to xg.exe and takes precedence: you do not need setup host. With the .NET global tool, which is meant for CI only and does not carry the host, install the host with xg init --no-interactive — see Getting Started. setup host remains for advanced management of the managed install.

It does not change the host of a winget or ZIP install

The CLI resolves the host in this order: the host bundled in the bin\ folder next to xg.exe, then the managed install root, then legacy locations beside the CLI. setup host writes only to the managed install root. On a winget install or an install from xrmghost-cli-<version>-full.zip, the bundled host in bin\ takes precedence and is never modified, so setup host does not change the host used by xg run. To update a winget install, run winget upgrade XrmGhost.Cli; to update a ZIP install, download the newer -full.zip from GitHub Releases and extract it over the same folder.

Description

The Plugin Framework Host is a .NET Framework 4.7.2 Windows process that XrmGhost uses to host Dataverse plugin assemblies in an isolated, out-of-process environment. The xg run command requires the Framework Host to be present and compatible before it can execute a plugin. If no host is found, run installs one into the managed root before executing; with --no-interactive it does not download anything, fails, and points to xg init --no-interactive.

setup host manages the managed install directly:

• Check (--check): reads the current installation state and reports it without making any changes.
• Install / Update (--update): downloads the latest compatible XrmGhost.Framework.Host package from GitHub Releases of the public repository — the distributed component comes from there, not from a NuGet feed — and extracts the executable to the managed install root under the XrmGhost user-data directory.

The managed install root is located at:

• Windows: %LOCALAPPDATA%\xrmghost\framework-host\current\
• Linux / macOS: ~/.local/share/xrmghost/framework-host/current/ (or ~/xrmghost/framework-host/current/ as fallback)

Note

The Framework Host executable (XrmGhost.Framework.Host.exe) targets the net472/win-x86 runtime payload. Running or installing it on non-Windows hosts is not supported — see Prerequisites.

Prerequisites

Requirement	Notes
Windows only	The Framework Host is a net472 win-x86 executable. setup host must be run on Windows.
Write access to the user-data directory	The install writes to %LOCALAPPDATA%\xrmghost\. No system-wide write access is required. If your environment restricts access to %LOCALAPPDATA%, rerun from an elevated terminal or adjust directory permissions.
GitHub reachable	The CLI resolves the Framework Host release through api.github.com and downloads the asset from github.com. Ensure both are accessible from the machine (on a build agent, through its proxy if it has one).

Options

Flag	Default	Description
--check	false	Inspect the current Framework Host installation state and print a status message. Does not modify the local installation. Cannot be combined with --update.
--update	false	Download and install the latest compatible Framework Host package from GitHub Releases into the managed install root. Also triggered automatically when the managed Framework Host is missing and no flag is specified. Cannot be combined with --check.

Mutual exclusion: --check and --update cannot be specified together. The command returns a validation error if both are provided.

Exit Codes

Code	Meaning
0	Success — either the status was printed or the install completed without errors.
1	Install failed — see the error message printed to the console for details.

Examples

Check the current Framework Host status

Report the installed version and whether an update is available, without changing anything:

xg setup host --check

Example output when the Framework Host is up to date:

Framework Host is current (1.0.2).

Example output when an update is available:

Framework Host 1.0.1 is installed. 1.0.2 is available from the official GitHub release source. Run 'xg setup host --update'.

Install or update to the latest Framework Host

Download and install the latest compatible Framework Host from GitHub Releases into the managed install root:

xg setup host --update

Example output on success:

Framework Host installed from the official GitHub release (1.0.2).

First-run install (no flag required)

If the managed Framework Host is missing, running setup host without any flag also triggers an automatic install into the managed root:

xg setup host

Troubleshooting

Symptom	Likely cause	Resolution
Failed to install XrmGhost.Framework.Host	The current user cannot write to the managed install root, or another process is locking the directory	Verify write permissions under %LOCALAPPDATA%\xrmghost\. Close any tools that may be locking the directory, or rerun from an elevated terminal.
The GitHub release source 'xrmghost/xrmghost' could not be reached	Network or proxy issue, or GitHub API rate limiting	Check that api.github.com and github.com are reachable from the machine, then retry.
Framework Host is incompatible or corrupted	The managed installation is not compatible with the current CLI	Run xg doctor --fix (or xg init) to repair the managed install, or xg doctor --verbose to inspect the resolved host path.
A newer host was installed but xg run still uses the old one	On a winget or ZIP install the bundled host in bin\ takes precedence over the managed root	Update the install: winget upgrade XrmGhost.Cli, or download the newer -full.zip and extract it over the same folder.

See Also

• xg init — first setup and repair of the installation

• xg run — execute a Dataverse plugin using the Framework Host

• xg doctor — diagnose Framework Host connectivity, license validity, and configuration health

• CLI Reference — overview of the CLI reference area