Upgrade your agent

Upgrades are manual. The console does not control Docker. Use the supported image tag or digest supplied by your console operator, not latest.

Before you start

Open Agents → your agent. Update available means a newer published build exists. Upgrade required means the current build is below the supported minimum. An unsupported newer build may need a supported older image instead. Unknown or incompatible versions can check in for diagnosis but cannot claim new scans. Online/offline status is separate from version compatibility.

Ask the console operator for the supported image and state-schema compatibility before replacing a container. Do not change deployment-wide version settings on an individual agent host.

Step 1: Record the existing setup

Inspect Agents → agent detail. Record the current image/digest, exact container name, existing state volume, canonical console origin, read-only mounts and execution mode. Do not copy credentials from the state volume into a command.

Step 2: Wait for running work

Wait for the active scan to finish. If stopping a busy worker, its running job becomes reclaimable after the last 300-second lease expires; partial findings remain deduplicated. Check ingestion/result status before replacement.

Step 3: Replace the container

Pull the release image, then stop and remove only the container:

docker pull '<published-supported-image@sha256:digest>'
docker stop '<existing-container-name>'
docker rm '<existing-container-name>'

Note: If the agent was started from a compose file, skip these commands and the ones in Step 4: change the image tag in compose.yaml (or the image variable in .env) to the supported release and run docker compose up -d. Compose replaces the container and reuses the state volume and mounts already written in the file.

Step 4: Reuse the identity and mounts

Recreate it using the SAME state volume and existing read-only mounts. Replace every bracketed placeholder; these are illustrative arguments, not a new enrollment command:

docker run -d --name '<existing-container-name>' --restart=on-failure \
  --read-only --cap-drop=ALL --security-opt=no-new-privileges \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --mount 'type=volume,src=<existing-state-volume>,dst=/var/lib/myrikeep' \
  --mount 'type=bind,src=<existing-secret-directory>,dst=/run/secrets,readonly' \
  -e DG_CRAWLER_API_URL='https://console.example.invalid' \
  '<published-supported-image@sha256:digest>'

Keep optional customer data mounts exactly as provisioned. Hosted operators add -e DG_CRAWLER_MANAGED=1 and retain that workspace's isolated secret mount and network policy. Hosted workers never have customer data mounts. No workspace API key or install token is needed. Never use latest, docker rm -v, delete the volume, clone it onto another host, or run two processes against it.

Step 5: Verify the upgraded agent

Verify the same agent UUID, new reported version, online status, desired/applied configuration, credential presence and a test scan. A stale/offline badge is based on last server contact, independently of build compatibility. A stale presence report is unknown; it does not prove remote authentication works.

Rollback uses a supported previous image with the same identity state schema and same volume/mounts. If the volume is lost, revoke the old identity and enroll a replacement. If enrollment's response was lost, revoke the orphan and use a new token/volume; enrollment is deliberately not automatically retried. A revoked volume exits 0 and cannot be reused for enrollment. See Install an agent.

Troubleshooting

State	What to do
Online but cannot pick up jobs	Check supported version, agent pause state, connection enablement and current credential presence.
`unknown` or stale presence	Wait for a fresh heartbeat for the current connection revision; check desired/applied configuration.
`missing` / Invalid credentials	Preserve the old read-only secrets mount and permissions; see Agent credentials.
`signin_required`	Keep the state volume; if OAuth state was lost, sign in again with Personal drives.
Offline after replacement	Check container status, supported image, state mount, HTTPS console origin and network access.
Revoked agent	A revoked volume cannot enroll again. Enroll a replacement with a new token and volume.

Limits

Do not run two processes against the same state volume, clone the volume to another host, delete it during an upgrade or use docker rm -v. Rollback is possible only to a supported image that can read the same state schema. Credentials and local mounts follow their connector guide. An upgrade does not add source permissions or recover lost OAuth tokens automatically.