Software Deployment

Package applications, scripts, and files, then target them at agents by ID, tag, or collection. Deployments run as multi-step jobs and report progress in real time.

Package types#

Every package declares a DeploymentType that tells the agent how to run its payload. The supported types are:

DeploymentType	Payload	Notes
`Executable`	`.exe`	Windows installer or executable
`Msi`	MSI	Windows Installer package
`PowerShell`	`.ps1`	PowerShell script
`Batch`	`.bat` / `.cmd`	Windows batch script
`Shell`	`.sh`	Linux shell script
`FileCopy`	Files	Copy payload files to a destination
`Python`	`.py`	Python script

Building a package#

Packages are managed via api/deployment-packages. The endpoint supports full CRUD, plus payload-file management and the build/deploy lifecycle:

Endpoint	Purpose
`GET/POST/PUT/DELETE api/deployment-packages`	Create, read, update, and delete packages
`GET/POST/DELETE api/deployment-packages/{id}/files`	Manage the payload files in a package
`POST api/deployment-packages/{id}/build`	Assemble the payload into `package.zip`
`POST api/deployment-packages/{id}/deploy`	Roll the package out to targets

Packages are stored on the server under Packages:StoragePath (default ./packages). The maximum upload size for a payload file is Packages:MaxUploadSizeGB (default 15).

If you just need to host a single large installer file — with a verified SHA-256 fingerprint and a time-limited, resumable download link — without building a multi-step job, use the Package Library instead.

Multi-step deployments#

A package contains an ordered list of steps that the agent executes in sequence. Each step uses one of the following executors:

Step executor	Action
`RunCommand`	Run an arbitrary command
`PowerShell`	Run a PowerShell script
`Batch`	Run a batch script
`Shell`	Run a shell script (Linux)
`ServiceStart`	Start a service
`ServiceStop`	Stop a service
`ServiceRestart`	Restart a service
`CopyFiles`	Copy payload files into place
`InstallApplication`	Install an application
`Uninstall`	Uninstall an application
`Wait`	Pause for a fixed interval
`Reboot`	Reboot the endpoint

Each step runs as SYSTEM by default, or as an alternate user when RunAs credentials are supplied on the step. For the full per-step field model — OS conditions, PowerShell conditions, success exit codes, timeouts, continue-on-error — and an end-to-end scripted example, see Deployment Package Steps.

Targeting#

A deployment is aimed at endpoints through two fields, which can be combined:

TargetAgentIds — a list of agent GUIDs to deploy to directly.
TargetTags — a list of strings; every agent carrying a matching tag is included.

Collections group agents for reuse and can be static or dynamic. They are managed via api/Collections, with {id}/members to list or edit membership and {id}/refresh to recompute it. Dynamic collections derive their membership from agent fields — see Collections for how to create static and metadata-based (dynamic) collections.

No ring / canary / wave batching

Athena does not have ring, canary, or wave staged-rollout batching for deployments. Targeting is direct: agent IDs, tags, and collections. Stage a rollout yourself by deploying to progressively broader tags or collections.

Monitoring progress#

While a deployment runs, the agent streams progress messages back to the server:

Overall progress — the current phase, percent complete, and download speed.
Per-step results — the outcome of each individual step.

Completed execution results are retrieved at GET api/deployment-packages/executions/{executionId}.

Scheduling#

Deployments can be scheduled rather than run immediately, using the Scheduler at api/Scheduler:

Endpoint	Purpose
`GET/POST/PUT/DELETE api/Scheduler`	Manage scheduled jobs (CRUD)
`POST api/Scheduler/{id}/pause`	Pause a scheduled job
`POST api/Scheduler/{id}/resume`	Resume a paused job
`POST api/Scheduler/{id}/trigger`	Run a job now
`POST api/Scheduler/validate-cron`	Validate a cron expression

The default deployment timeout is Scheduler:DefaultDeploymentTimeoutMinutes (default 120).

PowerShell automation#

The Athena PowerShell module (PowerShell 7+) wraps the REST API in cmdlets. Mutating cmdlets require the Admin role; read-only cmdlets require Operator. Connect with Connect-Athena, then create a package:

# Import the module and sign in (session is reused by later cmdlets)
Import-Module Athena
Connect-Athena -Server athena.example.com -Port 8443

# Create a package (Admin role required)
New-AthenaDeploymentPackage `
  -Name "7-Zip 24.08" `
  -FolderName "7zip-2408"