Skip to main content

ImmyBot

This is a how-to for RMM mass-deploy using ImmyBot. ImmyBot is a deployment tool. It installs software onto the computers it already manages.

A tenant is one company in ImmyBot. A deployment is an install rule. A license on that rule is where you store a registration token. ImmyBot passes the winning rule's license into the install script as $LicenseValue.

Every method still needs a verified installer and the right deployment scope.

Two install rules​

If you followed the workspace setup wizard as an MSP, you have two top-level SparkLogs organizations, Clients and Internal IT, each with its own registration token.

  1. Create a cross-tenant deployment for all computers, and select a license that holds the Clients token.
  2. Create a single-tenant deployment aimed at your own company, and select a license that holds the Internal IT token.

ImmyBot applies the narrower rule. Computers in client tenants get the Clients token. Computers in your own tenant get the Internal IT token. The script installs with $LicenseValue from whichever rule applied.

If your own tenant has child tenants, target the single-tenant rule at your tenant only and leave those children on the all-clients rule.

Tenant slug is the client id​

On each tenant, open Edit and set a slug (a short code you choose, such as contoso). Leave the slug in place after the first install. ImmyBot exposes it to scripts as $TenantSlug. The script sends that as RMMCLIENTID and sends the tenant name as CLIENTNAME.

CLIENTNAME is a display label. RMMCLIENTID is the link key. A blank slug fails the install.

The scripts​

Upload the Windows x64 EXE from Download and verify as the installer on one software version numbered 1.0.0. That number is an ImmyBot marker. The SparkLogs Agent updates itself, so do not add a new ImmyBot version when a new agent build ships. To change what a machine with no agent receives, replace the installer file on this same version.

Mark the software as requiring a license key. This is a starting point to adapt, not a supported partner package.

Detection. ImmyBot runs this before install. Return a version string when the service exists, and $null when it does not. Returning 1.0.0 keeps ImmyBot from treating a newer agent build as a missing install.

if (Get-Service 'SparkLogsAgent' -ErrorAction SilentlyContinue) {
  return '1.0.0'
}
return $null

Install. PowerShell, run as System. ImmyBot sets $InstallerFile, $InstallerLogFile, $LicenseValue, $TenantName, and $TenantSlug. Exit 0, 3010, and 1641 are success.

$ErrorActionPreference = 'Stop'

if (Get-Service 'SparkLogsAgent' -ErrorAction SilentlyContinue) { exit 0 }

$registrationToken = ($LicenseValue -as [string]).Trim()
if ([string]::IsNullOrWhiteSpace($registrationToken)) {
  throw 'No license found on this deployment. Attach the SparkLogs registration token to that install rule.'
}
$rmmClientId = ($TenantSlug -as [string]).Trim()
$clientName = (($TenantName -as [string]) -replace '"', '').Trim()
if ([string]::IsNullOrWhiteSpace($rmmClientId)) {
  throw "Tenant slug is empty for '$clientName'. Set a slug under Tenant, Edit, then run again."
}

$argLine = "/qn /norestart /l*v `"$InstallerLogFile`" EULA=ACCEPT " +
  "REGISTRATION_TOKEN=$registrationToken " +
  "RMMCLIENTID=$rmmClientId " +
  "CLIENTNAME=`"$clientName`""
$p = Start-Process -FilePath $InstallerFile -ArgumentList $argLine -Wait -PassThru
if ($p.ExitCode -notin 0, 3010, 1641) {
  throw "Install failed with exit code $($p.ExitCode)"
}

Property names are RMMCLIENTID and CLIENTNAME. Start-Process -Wait -PassThru is what makes PowerShell wait for the installer. See Troubleshooting. ImmyBot reads $InstallerLogFile into the session log.

Add it in ImmyBot​

  1. Confirm the SHA-256 of the EXE against Download and verify.
  2. Create the software. Licensing: license key. One version, 1.0.0, installer file is that EXE. Paste the detection script and the install script.
  3. Create two licenses. One holds the Clients token. One holds the Internal IT token.
  4. Cross-tenant deployment, target all computers, software should be installed, license is the Clients token.
  5. Single-tenant deployment, target your own company, same software, license is the Internal IT token.
  6. Set a slug on every tenant you will install, including your own. Set on the Edit Tenant page or directly on the Tenant List.

Pilot before the fleet rollout​

  1. Run a maintenance session on one computer in your own tenant.
  2. Run one on a computer in a small client tenant.
  3. In SparkLogs, confirm your computer landed under Internal IT and the client computer under Clients, each in a child organization whose link key is that tenant's slug.

If a client computer landed under Internal IT, the single-tenant rule is targeting that client. Point it at your own tenant only. Move the test computer with Change ownership on Configure > Agents. Installing again does not move it. See Moving devices and organizations.

Linking to SparkLogs organizations you already created​

SparkLogs auto-creates a direct child of the token's organization for each new RMMCLIENTID. If those organizations already exist, set each one's RMM client ID to the tenant slug before you install. SparkLogs links on RMMCLIENTID and/or PSACLIENTID.

Changing a slug later sends new installs to a different SparkLogs organization. Agents already enrolled stay where they are. See Changing RMM or PSA platforms.

After a rename in ImmyBot​

Renaming a tenant changes CLIENTNAME on a new install. It does not rename an agent that is already enrolled. Moving a computer to another tenant does not move it in SparkLogs. Use Change ownership. See Moving devices and organizations and Uninstall and reinstall.