Set the following environment variables when you install or run the Agent. On the host, private action runner settings use the DD_PRIVATE_ACTION_RUNNER_* prefix:

DD_API_KEY=<API_KEY> \
DD_APP_KEY=<APP_KEY> \
DD_SITE="<span class="js-region-param region-param" data-region-param="dd_site"></span>" \
DD_PRIVATE_ACTION_RUNNER_ENABLED=true \
DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST=com.datadoghq.kubernetes.*,com.datadoghq.remoteaction.* \
bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

DD_APP_KEY enrolls the runner as owned, the same as Fleet Automation. The application key needs the on_prem_runner_write scope. DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST takes a comma-separated list. Use bundle wildcards to allow the actions a runner in the Datadog Agent can run: com.datadoghq.kubernetes.* and com.datadoghq.remoteaction.*. To rely on the runner’s built-in default actions instead (read-only Remote Action actions, plus a set of read-only Kubernetes actions on the Cluster Agent), leave the allowlist unset.

After installation, go to Private Action Runners to verify your runner appears on the list.

Install or upgrade to Datadog Agent 7.81.0 or later, then edit C:\ProgramData\Datadog\datadog.yaml:

app_key: <YOUR_APP_KEY>

private_action_runner:
  enabled: true
  self_enroll: true
  actions_allowlist:
    - "com.datadoghq.kubernetes.*"
    - "com.datadoghq.remoteaction.*"

app_key enrolls the runner as owned, the same as Fleet Automation above; the application key needs the on_prem_runner_write scope.

Restart the Agent to apply the configuration:

Restart-Service -Force datadogagent

After the Agent restarts, go to Private Action Runners to verify your runner appears on the list.

The host process runs the node Agent runner. To run a runner in the Cluster Agent, use the Kubernetes (Helm) or Kubernetes (Operator) tab.

The Datadog Helm chart can enable the runner in two places:

• The node Agent runner, as a sidecar container. The node Agent runner is Linux-only.
• The Cluster Agent runner, in-process. The Cluster Agent runner is available through Helm or the Operator only (there is no standalone binary), and it requires leader election so that identity is coordinated across Cluster Agent replicas.

Create an API key with the Private Action Runner capability in Organization Settings, then store it in a Kubernetes secret that the chart reads through apiKeyExistingSecret:

kubectl create secret generic datadog-secret \
  --from-literal api-key=<DD_API_KEY>

This example enrolls the runner as ownerless (apiKeyOnlyEnrollment: true, using the API key only), which authorizes it with Execution Policies. For other enrollment options and how ownership works, see Enrollment and ownership.

Helm settings use the privateActionRunner.* key in camelCase. Create a values.yaml:

datadog:
  apiKeyExistingSecret: datadog-secret
  site: <span class="js-region-param region-param" data-region-param="dd_site"></span>
  clusterName: <YOUR_CLUSTER_NAME>
  remoteConfiguration:
    enabled: true
  privateActionRunner:
    enabled: true
    apiKeyOnlyEnrollment: true
    actionsAllowlist:
      - "com.datadoghq.remoteaction.*"
      - "com.datadoghq.script.*"
clusterAgent:
  enabled: true
  privateActionRunner:
    enabled: true
    apiKeyOnlyEnrollment: true
    actionsAllowlist:
      - "com.datadoghq.kubernetes.*"
      - "com.datadoghq.script.*"

For all available runner configuration options, see datadog.privateActionRunner and clusterAgent.privateActionRunner in the Helm chart. Install the chart:

helm repo add datadog https://helm.datadoghq.com
helm repo update
helm install datadog-agent datadog/datadog -f values.yaml

After installation, go to Private Action Runners to verify your runner appears on the list.

The Datadog Operator enables the runner through annotations on the DatadogAgent resource. The runner configuration in the -configdata annotation uses the private_action_runner.* key in snake_case. The Operator can enable both the node Agent runner and the in-process Cluster Agent runner.

Create an API key with the Private Action Runner capability in Organization Settings, then store it in a Kubernetes secret that the DatadogAgent resource reads through its credentials:

kubectl create secret generic datadog-secret \
  --from-literal api-key=<DD_API_KEY>

This example enrolls the runner as ownerless (api_key_only_enrollment: true, using the API key only), which authorizes it with Execution Policies. For other enrollment options and how ownership works, see Enrollment and ownership.

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
  annotations:
    agent.datadoghq.com/private-action-runner-enabled: "true"
    agent.datadoghq.com/private-action-runner-configdata: |
      private_action_runner:
        enabled: true
        api_key_only_enrollment: true
        actions_allowlist:
          - "com.datadoghq.remoteaction.*"
          - "com.datadoghq.script.*"
    cluster-agent.datadoghq.com/private-action-runner-enabled: "true"
    cluster-agent.datadoghq.com/private-action-runner-configdata: |
      private_action_runner:
        enabled: true
        api_key_only_enrollment: true
        actions_allowlist:
          - "com.datadoghq.kubernetes.*"
          - "com.datadoghq.script.*"
spec:
  global:
    clusterName: <YOUR_CLUSTER_NAME>
    site: <span class="js-region-param region-param" data-region-param="dd_site"></span>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key

Apply the manifest:

kubectl apply -f datadog-agent.yaml

As with Helm, the Cluster Agent runner requires leader election, and the node Agent runner is Linux-only. After you apply the manifest, go to Private Action Runners to verify your runner appears on the list.

1. Edit the private_action_runner.actions_allowlist section in /etc/datadog-agent/datadog.yaml.
2. Restart the Agent: sudo systemctl restart datadog-agent.

1. Edit the private_action_runner.actions_allowlist section in C:\ProgramData\Datadog\datadog.yaml.
2. Restart the Agent: Restart-Service -Force datadogagent.

1. Update actions_allowlist in both DatadogAgent manifest annotations: agent.datadoghq.com/private-action-runner-configdata and cluster-agent.datadoghq.com/private-action-runner-configdata.
2. Apply the updated manifest: kubectl apply -f datadog-agent.yaml.

1. Update privateActionRunner.actionsAllowlist (node Agent) or clusterAgent.privateActionRunner.actionsAllowlist (Cluster Agent) in values.yaml.
2. Apply the updated chart: helm upgrade datadog-agent datadog/datadog -f values.yaml.

Upgrade the Datadog Agent to the latest version. The runner is bundled with the Agent.

sudo apt-get update && sudo apt-get install datadog-agent

Or for RHEL/CentOS:

sudo yum update datadog-agent

Restart the Agent after the upgrade:

sudo systemctl restart datadog-agent

For detailed upgrade instructions, see Upgrade to Agent v7.

Download the latest Agent MSI installer from the Datadog Agent download page and run the installer, or use PowerShell:

# Download the latest installer
Invoke-WebRequest -Uri "https://s3.amazonaws.com/ddagent-windows-stable/ddagent-cli-latest.msi" -OutFile ddagent-cli-latest.msi

# Run the installer
Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /i ddagent-cli-latest.msi'

Restart the Agent after the upgrade:

Restart-Service -Force datadogagent

Update the Datadog Operator and Agent image versions in your DatadogAgent manifest.

1. Update the Datadog Operator:

   helm repo update
   helm upgrade datadog-operator datadog/datadog-operator \
       --set image.repository=registry.datadoghq.com/operator \
       --set image.tag=latest
   

   You can pin a specific version. To browse available tags, use Docker Hub.

2. Update the Agent image versions in your datadog-agent.yaml manifest:

   override:
     nodeAgent:
       image:
         name: registry.datadoghq.com/agent:<NEW_AGENT_VERSION>
     clusterAgent:
       image:
         name: registry.datadoghq.com/cluster-agent:<NEW_AGENT_VERSION>
   

3. Apply the updated manifest: kubectl apply -f datadog-agent.yaml.

4. Verify the update:

   kubectl get pods
   kubectl logs -l app.kubernetes.io/component=cluster-agent --tail=100 | grep private
   

The Cluster Agent runner keeps its identity across the update, since it stores it in a shared Kubernetes secret. The node Agent runner stores its identity in a file: if that path isn’t backed by a persistent volume, an update can wipe the identity and force the runner to re-enroll. See Identity storage on Kubernetes.

Updating the runner is part of the standard Datadog Agent Helm chart upgrade process.

helm repo update
helm upgrade datadog-agent datadog/datadog -f values.yaml

For detailed upgrade instructions, see Upgrading Datadog Helm.

Update the version variables in your Terraform configuration:

locals {
  helm_operator_version = "<NEW_OPERATOR_VERSION>"
  agent_version         = "<NEW_AGENT_VERSION>"
  # ...
}

Apply the changes:

terraform plan
terraform apply -var="datadog_api_key=<YOUR_API_KEY>" -var="datadog_app_key=<YOUR_APP_KEY>"