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:

Building a package#

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

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.

Create a package in the console#

In Athena, an application to roll out is modelled as a deployment package. You can build one from the web console without writing any API calls. Creating packages requires the Operator or Admin role.

1. In the left navigation, open Deployments.
2. Click Create First Package (or the add/create button on the packages list) to open the new-package editor.
3. Under Package Information, fill in:
   • Package Name — the display name of the package (for example your application's name).
   • Folder Name — a short, unique name Athena uses to store this package's files on the Athena server. It is not a network share or a folder on your own computer, and not a UNC path — just a single plain name (no slashes, backslashes, drive letters or ..). Athena creates a subfolder of that name under its packages storage directory on the server (by default Data/Deployments/<Folder Name>/, which an admin can relocate with the Deployments:PackagesPath setting) and puts the installer/source files you add to the package there.
   • Description — optional notes about the package.
4. In the Deployment Steps panel, click Add Step for each action the agent should run in order — for example run an installer, run a PowerShell, batch or shell script, or copy files. For each step set its type and options (and, where a step needs a payload, select or upload the installer/source file). See Multi-step deployments for the available step executors.
5. Click Save to store the package. It now appears in the Deployments list.

From there you can target the package at agents by ID, tag, or collection and roll it out (or schedule it for later). Prefer automation? The same package can be created via the REST API or PowerShell — see Building a package and PowerShell automation.

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:

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.

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}. To follow executions live in the console and drill into each machine’s step output, see Tracking Deployments: Active & History.

Scheduling#

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

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"