Deploy the Agent on Windows

This guide shows you how to install and register the octoja Agent on a Windows system.

Requirements

• An octoja account with the Agent Management permission — without it, Administration → Agent Deployment does not appear in your navigation
• Windows 10 / Windows Server 2016 or newer — see the table below for details and legacy versions
• Microsoft Visual C++ Redistributable (x64 or ARM64), version 14.51.36247.0 or newer, on the device. Quick Install checks the installed version and installs or upgrades it when necessary; for Manual Install and Automatic Rollout, install a supported version before the MSI runs
• Microsoft .NET Framework 4.7.2 or later. Quick Install installs version 4.7.2 if the requirement is not met and preserves newer versions. For Manual Install and Automatic Rollout, install it and complete any required restart before running the MSI
• Administrator account on the device
• Internet access (outbound HTTPS on port 443)

Supported Windows versions

Allow installation downloads

Quick Install needs outbound HTTPS access to cdn.octoja.com and your octoja instance. If it installs or updates the Visual C++ Redistributable, also allow aka.ms and its download destination, download.visualstudio.microsoft.com. For .NET Framework installation, allow go.microsoft.com and its download destination, download.microsoft.com.

For ongoing agent communication and feature-specific requirements, see Configure firewall access for the agent.

Steps

1. In octoja, go to Administration → Agent Deployment.
2. In Step 1 – Settings, review the deployment mode (open deployment or token-based).
3. In Step 2 – Choose Platform, click Windows.
4. In Step 3 – Choose Installation Method, pick the method you want:
   • Quick Install — a single PowerShell command that auto-detects architecture and installs silently. Best for one device at a time.
   • Manual Install — download the ZIP archive, extract the MSI, and install it yourself with a wizard or silent flag.
   • Automatic Rollout — generate the Intune or Group Policy (GPO) command for deploying to many devices at once.
5. Copy the command or download the installer from the on-screen panel. Keep the panel open — the command contains your unique server URL.
6. Run the command on the Windows device (see below).
7. Back in octoja, go to Devices. The device appears within seconds.

Quick Install (recommended for one device)

Copy the PowerShell command from the deployment page and paste it into an elevated PowerShell on the target device.

The PowerShell command will look similar to this:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL'

If token-based deployment is enabled, the command includes a -Token argument — copy it verbatim:

& ([scriptblock]::Create((irm https://cdn.octoja.com/installer/install.ps1))) -OctojaUrl 'https://YOUR-OCTOJA-URL' -Token 'YOUR-TOKEN'

The script checks prerequisites and automatically installs missing Microsoft Visual C++ Redistributable and .NET Framework components. It detects the device architecture (x64 or ARM64), downloads the correct package, extracts the MSI it contains, and runs it silently. It requires an administrator PowerShell session.

Windows Server 2016 (and older Windows): enable TLS 1.2 first. On these systems Windows PowerShell still defaults to an older TLS version, so the command can fail at the download step (irm https://cdn.octoja.com/installer/install.ps1) with a connection error such as "The underlying connection was closed: An unexpected error occurred on a receive." — before the installer's own TLS handling can take effect. In the same elevated PowerShell session, switch to TLS 1.2, then run the octoja command again:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Certificate trust is a different failure. If Resolve installer URL ends with "Could not establish trust relationship for the SSL/TLS secure channel", changing the TLS version will not help. The Quick Install command downloads the script from cdn.octoja.com; after the script starts, it contacts your octoja instance to resolve the installer URL and then downloads the package from the CDN. A firewall or proxy that performs SSL/TLS deep inspection can replace either site's certificate with one issued by its own certificate authority. Windows rejects that replacement when the authority is not trusted on the device.

Ask your network administrator to exempt both your octoja instance URL and cdn.octoja.com from SSL/TLS inspection. On the affected device, open both addresses in a browser and inspect each certificate's Issuer. If the issuer belongs to your firewall, proxy, or organization rather than the site's public certificate authority, the connection is being inspected.

For basic DNS and port checks, test both destinations. Replace https://YOUR-OCTOJA-URL with your complete instance URL. These checks do not validate certificate trust:

$instanceHost = ([Uri]'https://YOUR-OCTOJA-URL').Host
Test-NetConnection $instanceHost -Port 443
Resolve-DnsName $instanceHost
Test-NetConnection cdn.octoja.com -Port 443
Resolve-DnsName cdn.octoja.com

Manual Install (MSI)

Before you run the MSI: make sure Microsoft Visual C++ Redistributable (x64 or ARM64) and .NET Framework meet the requirements above, and complete any required restart. Quick Install installs missing prerequisites for you; the MSI expects them to be there already.

Choose Manual Install on the deployment page to see the Download x64 / Download ARM64 button. The download is a ZIP archive — extract it first, then run the contained MSI (octoja.Launcher.<version>.<arch>.msi) with msiexec:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL"

Append /qn for silent installation with no UI:

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" /qn

If an enrollment token is required, add TOKEN="...":

msiexec /i octoja.Launcher.<version>.<arch>.msi OCTOJA_URL="https://YOUR-OCTOJA-URL" TOKEN="YOUR-TOKEN" /qn

Automatic Rollout (Intune / Group Policy)

The Automatic Rollout card walks you through each deployment tool. The MSI itself comes from the Manual Install download — extract it from the ZIP archive first.

Roll out with Group Policy

Group Policy software installation can't pass MSI properties on its own. That's why octoja gives you a ready-made transform file (octoja.Launcher.<version>.mst) that already contains your server URL and enrollment token. It sets the same OCTOJA_URL and TOKEN properties as the manual msiexec command.

1. On the Automatic Rollout card, select the Group Policy (GPO) tab and click Download transform (.mst). If you change the enrollment token later, simply download the transform again.

2. Copy the MSI and the .mst file to a network share and use UNC paths such as \\server\share\…. The installation runs under the computer account, so the target computers need read access to the share and to the files (NTFS).

3. In a GPO, go to Computer Configuration → Policies → Software Settings → Software installation and add the MSI as a new package. Choose Advanced as the deployment method — this is the only way to attach the transform.

   

4. On the package's Modifications tab, click Add and select the .mst file through the same UNC path.

   

5. Link the GPO to the OU that contains the target computers. The agent installs the next time each computer starts. Microsoft's Group Policy software-installation guide describes the console steps in more detail.

Filtering by group? If you limit the GPO's Security Filtering to a group such as Domain Computers, keep in mind that domain controllers aren't members of it (Microsoft's group reference). If your domain controllers should get the agent as well, add them to the filter and to the share permissions too.

Keep the agent installed: Group Policy only removes software while a computer starts. An unintended uninstall therefore often shows up days or weeks later, after a routine reboot. Two settings make the difference:

• Leave "Uninstall this application when it falls out of the scope of management" cleared. You'll find it on the package's Deployment tab. If it's selected, Windows removes the agent from every computer that no longer falls under the GPO — for example after you change the filter or move a computer to another OU.

  

• Keep the software when you remove the package. To roll out a new MSI or transform, you remove the package and add it again. The Remove Software dialog preselects Immediately uninstall the software from users and computers, which uninstalls the agent at the next start — and if the new package then fails to install, the device is left without an agent. Choose Allow users to continue to use the software, but prevent new installations instead. Installed agents stay enrolled; a new token only applies to new installations.

  

Windows 10 and 11: By default, these systems don't wait for the network at startup and often skip the software installation as a result. In the same or a separate GPO, enable Computer Configuration → Policies → Administrative Templates → System → Logon → Always wait for the network at computer startup and logon.

Use a preconfigured settings file

Under Manual Install on the agent deployment page, click installer.settings.json to download the preconfigured file and place it next to the MSI. This avoids passing the server URL and enrollment token on the command line.

Then run msiexec /i octoja.Launcher.<version>.<arch>.msi /qn — the installer reads the settings file automatically.

Parameter reference

Verify the installation

1. In the Windows Services console, confirm both agent services are Running: Octoja Agent (Octoja.Agent) and Octoja Launcher (Octoja.Launcher).
2. In octoja, go to Devices — the device appears within seconds of the install finishing.

Need an enrollment token? See Configure Agent Enrollment Tokens.

FAQ