Updating the agent

Agents deployed on the rolling stable tag auto-update weekly on every cloud shape (EC2 via an in-host refresh cron, Fargate via an EventBridge Scheduler that forces a new deployment). Pinned agents, and the local shapes, never self-update: when a newer version is available, Argus surfaces a notice in the dashboard (a badge on the agent, and an admin notification) and you update on your own schedule using the steps below.

The one rule: update in place, keep the identity

An agent’s identity is its enrollment token / persisted API key, not its image. Updating swaps the container image on the existing deployment; the agent reuses its key and keeps the same identity, history, and cloud-account binding.

• No new enrollment token. Reuse the one you already deployed with.
• No second agent. You are replacing the image under the same agent, not registering another one.
• Redeploying from scratch with a fresh token would create a duplicate agent. Do not do that to upgrade.

stable vs a pinned version

The version you choose at deploy time (the deploy drawer’s Agent version selector, or the agent_image_tag / agent_container_image / AgentImage value in your IaC) decides how updates behave:

• stable is a rolling tag that always points at the latest release. On the shapes that auto-update, moving to a new release is automatic; on the rest you re-pull stable.
• A pinned version (a specific release tag) never moves on its own. You upgrade by changing the pin and applying, which is the right choice for production change control.

To switch between them, change the version value and redeploy that shape (see below). Nothing about the agent’s identity changes.

Does it auto-update?

Shape (on stable)	Auto-updates?	How an update reaches it
Cloud DIY EC2 (Terraform)	Yes	A weekly cron pulls the image and restarts only if the digest actually changed.
Cloud managed EC2 (CloudFormation)	Yes	The same weekly digest-gated cron, installed by the stack’s UserData.
Cloud managed / DIY Terraform Fargate	Yes	A weekly EventBridge Scheduler forces a new deployment, so the service re-pulls stable.
Cloud DIY ECS task JSON	No	Register a new task-def revision and update the service.
Local Docker Compose / docker run	No	Pull and recreate the container.
Local offline tarball	No	Re-import the new image and recreate.
Any shape, pinned :vX.Y.Z	No (by design)	Change the pin, then apply for that shape.

Auto-update always means stable. A pinned agent is always a manual version bump, regardless of shape. The weekly schedules are anchored per deployment, so a fleet updates staggered across the week rather than all at once. Deployments created before the updater shipped do not have it; update the stack (or module ref) to the current template version to pick it up. On managed EC2 that is a UserData change, so it replaces the instance - see the note under EC2 - CloudFormation before you run it.

Do not re-point an existing stack at the v2 template

The managed templates are versioned. Stacks created before 2026-08-21 use argus-managed-{ec2,fargate}-v1.yml; new deploys use -v2.yml, which gives every IAM role an /argus/ path and an explicit name.

Those are replace-and-recreate changes. Pointing a running stack at v2 makes CloudFormation delete the agent’s role and instance profile and create new ones with different ARNs - verified against a real stack, not inferred. The update reports success while the agent’s AWS identity changes underneath it.

Argus itself is fine either way: AWS accounts are agent-based, so the account record is keyed on your 12-digit account id and the agent presents credentials from its own instance profile or task role. The risk is on your side. Anything you granted to the OLD role ARN - a KMS key policy, a bucket policy, an SCP condition, a cross-account trust - stops matching a principal that no longer exists. Those failures surface as no findings rather than as an error, which reads as clean rather than unread.

v1 stays published and supported indefinitely, and it keeps receiving permission updates, so there is nothing you need to do. Move to v2 only by deploying a new stack and retiring the old one once the new agent is reporting.

Update steps per shape

All commands assume you keep the same enrollment token / API key. Substitute the version you want (stable or vX.Y.Z).

EC2 - Terraform (DIY)

On stable, the weekly cron already keeps it current; to apply a waiting update immediately:

# On the instance (SSM Session Manager or SSH):
sudo /etc/cron.weekly/argus-agent-refresh

To move a pinned instance to a new version, change agent_container_image in the Terraform module and terraform apply. The instance pulls the new image and restarts.

EC2 - CloudFormation (managed)

On stable, the stack’s weekly refresh cron already keeps it current. The service also pulls the image each time it starts, so restarting the service (or rebooting the instance) applies whatever stable currently points at immediately:

# On the instance (SSM Session Manager or SSH):
sudo systemctl restart argus-agent

To move to a pinned version, update the stack with a new AgentImage parameter set to a specific release tag instead of :stable, then restart the service as above.

A pinned managed-EC2 version change replaces the instance, and that is expected

AgentImage is baked into the stack’s UserData, so changing it rewrites UserData and CloudFormation replaces the EC2 instance rather than updating it in place. The new instance boots, reads the same enrollment token from Secrets Manager, and re-enrols into the same agent record - the token is reusable and the agent is matched, not recreated.

So you should expect a short gap while the instance is replaced, and you should not mint a new enrollment token for the upgrade. Generating a fresh token creates a second agent alongside the first, which is the duplicate this page warns about at the top.

Fargate (managed or Terraform)

On stable, both the managed template and the Terraform module provision a weekly EventBridge Scheduler that forces a new deployment for you (a running Fargate task never re-pulls its image on its own). To apply a waiting update immediately instead of waiting for the weekly tick, force a deployment yourself:

aws ecs update-service \
  --cluster argus-agent-<customer-or-stack> \
  --service argus-agent-<customer-or-stack>-baseline \
  --force-new-deployment

To move a pinned service, change agent_image_tag (Terraform) or the AgentImage parameter (managed template) and apply; then force-new-deployment if the task definition did not already roll.

ECS task JSON (DIY)

Register a new task-definition revision with the new image, then point the service at it:

# Edit the "image" field to the new version, then:
aws ecs register-task-definition --cli-input-json file://task.json
aws ecs update-service --cluster <cluster> --service <service> --task-definition argus-agent

Docker Compose

# Same directory, same .env, same volume - just pull and recreate:
docker compose pull
docker compose up -d

docker run

docker pull ghcr.io/argusdspm/argus-agent:stable   # or :vX.Y.Z
docker rm -f argus-agent
# Re-run with the SAME -e env vars and the SAME -v argus_agent_data volume as
# your original docker run so the persisted key (and identity) carries over.

Offline / air-gapped tarball

Rebuild the tarball on a box with ghcr.io access (docker pull + docker save), move it to the target, then:

docker load -i argus-agent-<version>.tar
docker rm -f argus-agent
# Recreate with the same env + volume as before.

Minimum-version floors

An administrator can set a recommended floor (soft: you get a notice, the agent keeps working) and a minimum floor (hard: below-minimum agents are refused with HTTP 426 and stop taking work until upgraded).

The hard floor is date-gated: it only takes effect on its configured effective date, so you always get runway (typically about two weeks) between the announcement and the cutoff. Update any lagging agents before that date to avoid an interruption.

Verifying an update

After updating, confirm the new version the same way you verify any deploy: the agent’s row on the Agents page shows the new version, and its status returns to online. See Verifying connection.