Active Directory Agent Deployment

Roll the Hermes agent out to your whole domain from one PowerShell console. Two cmdlets in the Athena module — Get-AthenaAdComputer to discover machines from Active Directory, and Install-AthenaAgent to push and start the agent on each one over PowerShell Remoting (WinRM) — replace the old push-tool and logon-script approach. There is no SMB admin share and no WMI: the agent binary, the registration server address, and a run-scoped registration token can all come straight from the server you're connected to, so a full rollout is a single pipeline. Windows only.

These cmdlets ship in the same Athena PowerShell module as the rest of the toolkit — install and import it once (see PowerShell Module) and both commands are available. No separate download.

How it works#

The rollout has two stages that pipe into each other:

Discover — Get-AthenaAdComputer queries Active Directory over LDAP and emits one object per computer account (name, DNS host name, OS, and more). This talks to a domain controller, not to Athena, so it needs no Athena role.
Install — Install-AthenaAgent takes those computers (by pipeline), opens a WinRM session to each, copies the agent executable, writes the agent's appsettings.json, registers the HermesAgent Windows service, and starts it. Each host produces a result object you can summarize.

The agent it installs behaves exactly like any other enrolled agent: it connects outbound only to the server on port 8444 and authenticates with a per-agent X.509 certificate. See Agent Enrollment for the certificate and check-in details.

Prerequisites#

Requirement	Why
Windows with the Athena PowerShell module imported	Both cmdlets are Windows-only; they use LDAP and WinRM.
WinRM / PowerShell Remoting enabled on each target	The push uses `New-PSSession` + `Copy-Item -ToSession` and remote service creation — TCP 5985 by default.
A local-administrator credential valid on the targets	Passed as `-Credential`; required to create and start the Windows service.
Active Directory read access	`Get-AthenaAdComputer` needs to read computer accounts (any domain user by default; pass `-Credential` to bind as someone else).
`Connect-Athena` as an Admin (for `-FromServer`)	Pulling the active agent binary and auto-minting a registration token are Admin-gated on the server.

No agent role required to discover

Get-AthenaAdComputer never calls the Athena server — it reads directly from a domain controller. Only Install-AthenaAgent -FromServer needs an Admin Athena session (to fetch the binary and mint a token). Supply your own binary and token and you can install without an Athena session at all.

Discover computers with Get-AthenaAdComputer#

Get-AthenaAdComputer queries AD over LDAP (no RSAT / ActiveDirectory module needed). By default it returns enabled computer accounts in the current domain. Filters narrow the set before you install:

Parameter	Purpose
`-Name`	Wildcard filter on the computer name, e.g. `'WEB*'`.
`-OperatingSystem`	Wildcard filter on the OS, e.g. `'Server'`.
`-SearchBase`	Distinguished name to search under, e.g. `'OU=Servers,DC=corp,DC=local'` (defaults to the domain root).
`-Server`	Domain / domain controller to bind to (defaults to the current domain).
`-LdapFilter`	An extra raw LDAP clause, AND-combined with the built-in filter.
`-IncludeDisabled`	Include disabled computer accounts (excluded by default).
`-Credential`	Bind to AD as a specific principal (useful from a non-domain-joined workstation).

Each returned object carries these properties:

Property	Meaning
`Name`	Computer account name.
`DnsHostName`	FQDN — this is what the install pipeline targets.
`OperatingSystem` / `OSVersion`	Reported OS and version.
`DistinguishedName`	Full DN of the account.
`Enabled`	Whether the account is enabled.
`LastLogon`	Last logon timestamp (useful to skip stale accounts).

# Enabled server computer accounts in the current domain
Get-AthenaAdComputer -OperatingSystem '*Server*'

# Computers named NUC* under a specific OU
Get-AthenaAdComputer -SearchBase 'OU=Lab,DC=corp,DC=local' -Name 'NUC*'

# Query a specific DC with explicit credentials (workstation not domain-joined)
$cred = Get-Credential 'CORP\Administrator'
Get-AthenaAdComputer -Server 10.10.0.2 -Credential $cred -OperatingSystem '*Server*'

# Include disabled accounts and review last-logon
Get-AthenaAdComputer -IncludeDisabled | Format-Table Name, OperatingSystem, Enabled, LastLogon

Push the agent with Install-AthenaAgent#

Install-AthenaAgent accepts computers by name or straight from the discovery pipeline (it binds the DnsHostName property). It is a high-impact command: it supports -WhatIf and prompts for confirmation by default. Use -Confirm:$false or -Force to skip the prompt for an unattended run.

Where the installer comes from#

Two parameter sets choose the agent binary:

-FromServer — downloads the active Windows agent from the Athena server you're connected to. Requires an Admin Connect-Athena session. The download is verified against the server-reported SHA-256 before anything is pushed; a mismatch aborts the whole run.
-InstallerPath — pushes a local agent executable (or bundle) you supply instead. With this set you must also pass -Server (the registration URL) and, unless an Athena session is available to mint one, a -RegistrationToken.

Registration token & server URL#

-RegistrationToken is optional. When you omit it and are connected to Athena, the cmdlet auto-mints a token scoped to this run — its usage count is set to the number of targets and it is valid for 24 hours — so every agent can register exactly once. Supply a token explicitly to reuse an existing one. For -FromServer, -Server also defaults to the connected server's host on the agent gRPC port 8444, so you rarely pass it by hand.

Key parameters#

Parameter	Default	Purpose
`-ComputerName`	—	Target host name(s) / FQDN. Accepts pipeline input (binds `DnsHostName`).
`-FromServer`	(default set)	Download the active Windows agent from the connected server.
`-InstallerPath`	—	Push a local agent executable / bundle instead.
`-RegistrationToken`	auto-minted	Token for first registration; omit to mint one scoped to the run.
`-Server`	from session	Agent registration URL(s), typically `https://host:8444`.
`-Credential`	—	Local-admin credential used for the remote session on each target.
`-Authentication`	`Default`	WinRM auth mechanism (`Negotiate`, `Kerberos`, `Credssp`, …).
`-ThrottleLimit`	`5`	Maximum concurrent installs (1–64).
`-TimeoutSec`	`300`	Per-host session / operation timeout (30–3600).
`-SkipConnectionTest`	off	Skip the fast WinRM (TCP 5985) reachability pre-check.
`-SkipCertificateCheck`	off	For a self-signed / dev server — see the note below.
`-Force`	off	Skip the confirmation prompt.

Fast fail on unreachable hosts

By default each target is first probed on WinRM (TCP 5985). A host that's down or blocked is reported Unreachable within about five seconds instead of hanging on the session timeout. Pass -SkipConnectionTest only if a target listens on a non-default port or deliberately blocks the probe.

The end-to-end rollout#

Preview first with -WhatIf — a dry run downloads nothing, mints no token, and opens no sessions; every target is reported Skipped. Then run for real:

# 1) Preview against every discovered server (no changes)
Get-AthenaAdComputer -OperatingSystem '*Server*' |
    Install-AthenaAgent -FromServer -Credential $labAdmin -WhatIf

# 2) Zero-touch install: binary, server URL and token all sourced from Athena
Connect-Athena -Server athena01 -Credential (Get-Credential)
Get-AthenaAdComputer -OperatingSystem '*Server*' |
    Install-AthenaAgent -FromServer -Credential $labAdmin -Confirm:$false

Push a local binary to named hosts, reusing an existing token:

Install-AthenaAgent -ComputerName WEB01,WEB02 -InstallerPath .\Hermes.Agent.exe `
    -Server https://ath01:8444 -RegistrationToken $tok -Credential $c

Bulk install across an OU, ten at a time, then summarize the outcomes:

$results = Get-AthenaAdComputer -SearchBase 'OU=Servers,DC=corp,DC=local' |
    Install-AthenaAgent -FromServer -Credential $c -ThrottleLimit 10 -Confirm:$false

$results | Group-Object Status | Select-Object Name, Count
$results | Where-Object Status -ne 'Success'

Reading the results#

Install-AthenaAgent emits one result object per host and never throws for a single-host failure, so one bad machine can't stop the rollout. Each object has:

Field	Meaning
`ComputerName`	The target host.
`Status`	`Success`, `Failed`, `Unreachable`, or `Skipped` (`-WhatIf` / declined confirmation).
`Steps`	The stages reached, e.g. `reachable`, `session-opened`, `dir-ready`, `exe-copied`, `config-written`, `service-Running` — handy for pinpointing where a host failed.
`Duration`	Seconds spent on that host.
`Error`	The failure message, when `Status` isn't `Success`.

On success the agent is installed to C:\Program Files\Athena System\Hermes Agent, the HermesAgent service is set to start automatically and is running, and the machine appears on the Agents page once it checks in. Re-running against a host that already has the agent is safe: the service is stopped, the binary refreshed, and the service reconfigured and restarted.

Self-signed / lab servers

Against a dev Athena that uses a self-signed certificate, add -SkipCertificateCheck. It disables TLS validation for the binary download only (the download is still SHA-256-verified) and writes ValidateServerCertificate=false into the deployed agent's config so it will trust that server when it registers. Leave it off in production — the agent runs with high privilege, so a trusted certificate matters.

Troubleshooting#

Symptom	Likely cause / fix
`Status = Unreachable`	Target is off or WinRM (TCP 5985) is blocked. Enable PowerShell Remoting on the host, or use `-SkipConnectionTest` if it listens elsewhere.
Session opens but service creation fails	The `-Credential` isn't a local admin on the target. Supply an account with rights to create and start a service.
"Not connected to Athena…"	`-FromServer` (or auto-token minting) needs an Admin `Connect-Athena` session. Connect first, or pass `-InstallerPath`, `-Server` and `-RegistrationToken` explicitly.
"No active Windows agent binary…"	No Windows agent build is published/active on the server. Upload and activate one (see Agent Binaries & Updates) or use `-InstallerPath`.
SHA-256 mismatch, run aborts	The downloaded binary failed its integrity check — a tampered or truncated download. The run is aborted by design; retry from a trusted network.
Cross-domain / non-joined workstation	Point `Get-AthenaAdComputer -Server <dc> -Credential <cred>` at the target DC, and use an appropriate `-Authentication` mechanism for the install.

For deeper agent-side diagnostics, the installed agent logs to C:\ProgramData\Hermes\Logs\hermes-.log on each host.

Air-gapped rollouts

Everything here stays inside your network: discovery reads your domain controller and the install reaches only your Athena server and the targets. In an isolated environment, supply the agent with -InstallerPath and a token if the console can't be reached from your admin workstation. See Air-Gapped Operation.