
dt-setup-oneagent
Reference knowledge for installing, uninstalling, or creating-and-installing Dynatrace OneAgent across VM/server, Kubernetes (Operator + DynaKube), AWS Lambda (layer + env vars, plus optional fresh function provisioning), Windows hosts, remote Linux hosts / EC2 instances over SSH, and Azure VMs / VM Scale Sets. Returns documented endpoints, env vars, token scopes, and copy-paste-ready commands. Returns the exact commands to run rather than executing them. Use when the user asks to install or uninstall OneAgent, or asks "how do I…", "what URL/scope/var do I need for…", or "explain the OneAgent deployment for X".
- Installs
- 502
- Last 24h
- +12
- Trending rank
- #8060
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/dynatrace/dynatrace-for-ai --skill dt-setup-oneagent- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dt-setup-oneagent automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Deploy Dynatrace OneAgent — knowledge reference
This skill is reference-only. It contains the documented endpoints, environment variables, token scopes, and commands that an operator (or another agent) needs to install OneAgent manually across the supported targets. It executes nothing.
This skill gives you the commands; it does not run them. Follow the procedure for the target you need, substituting the environment URL and token as documented below.
Hard rules for any agent consuming this skill
- Operate only on resources the user explicitly named. Never create a placeholder/test Lambda, IAM role, K8s namespace, secret, S3 bucket, EC2 instance, or any other fixture on your own initiative — not to "demonstrate", not "while we're at it", not preemptively. If the named resource doesn't exist and the user hasn't asked for it to be created, stop and ask. Side resources (additional Secrets Manager entries, monitoring, helper stacks) must not be provisioned silently — surface them as confirmation questions with the exact definition first.
- Explicit user-driven create modes are fine. When the user passes
--create(or explicitly says "yes, create it" after being asked), provisioning exactly the resources documented for that mode is the right thing to do — see Create a new function and install OneAgent in references/aws-lambda.md for the documented set. Don't second-guess the function name the user typed: do not pattern-match on names like "test", "demo", "scratch", "tmp" and refuse, warn, or insist on an alternative. The input is authoritative; the rule above is about silent or unsolicited creation, not user-requested creation. - Never persist the API token. The token's only job is to (a) authenticate the OneAgent artifact download / layer-ARN lookup and (b) get handed to the target system (Lambda env var or Secrets Manager, Linux installer, DynaKube secret) as part of the install. Do not cache it to local files, write it to scratch scripts, leave it in shell history, copy it into PR descriptions, or store it anywhere outside the target system that strictly needs it. Treat each run as fresh: supply via env var or 0600 file, use, discard.
- Never echo or log the API token. When you have to reference it in a command, write
$DT_API_TOKENor an elided prefix (dt0s16.…,dt0c01.…). Don't paste the literal value into prose. - Never assume the env URL, and confirm the tenant before installing. Targeting the wrong environment fails silently: the install succeeds and the host or function simply reports to a tenant nobody is watching. An environment URL the user stated explicitly always wins over anything derived from a tool default or a previous run — never let a cached or discovered value override it. State the tenant you are about to use and let the user correct you. Tenant IDs (
abc12345) and labs vs. prod determine the correct host. - Writes that take a collection replace it — read, merge, then write. Several APIs here accept a whole collection and overwrite whatever was there:
aws lambda update-function-configurationdoes this for both--environmentand--layers, so sending only the Dynatrace values silently deletes the function's own variables and any other layers. Always read current state, merge your additions into it, and write the union back. Take a rollback snapshot before the first write. This applies wherever you are about to replace a set rather than add to one. - Deriving the env URL from dtctl.
dtctl config current-contextreturns only the context name (e.g.my-env), not a URL. The URL comes fromdtctl config describe-context <ctx>. Do not pipe that straight intojq: some dtctl versions ignore-o jsonand print a human table (Environment: https://…) while still exiting 0, so jq dies on a parse error and takes anyset -e -o pipefailscript down with it. Check the output really is JSON first, and fall back to scraping theEnvironment:line:
CTX="$(dtctl config current-context 2>/dev/null || true)"
OUT="$(dtctl config describe-context "$CTX" -o json 2>/dev/null || true)"
if printf '%s' "$OUT" | jq -e . >/dev/null 2>&1; then
DT_ENV_URL="$(printf '%s' "$OUT" | jq -r '.environment // .url // empty')"
else
DT_ENV_URL="$(printf '%s' "$OUT" | awk 'tolower($1) ~ /^(environment|url):$/ {print $2; exit}')"
fi
URL normalization
Dynatrace's "new platform" URLs and the classic OneAgent installer endpoints differ. Before constructing installer URLs, convert:
| Input (Dynatrace UI / docs) | Use for installer endpoints |
|---|---|
https://<id>.apps.dynatrace.com | https://<id>.live.dynatrace.com |
https://<id>.<region>.apps.dynatracelabs.com | https://<id>.<region>.dynatracelabs.com |
| Anything else | unchanged |
The tenant ID is the first dot-separated segment (<id>).
Token types and the Authorization header
Two token families are in play, and the Authorization scheme is chosen by the token's prefix, not by which endpoint you call:
| Token | Prefix | Header |
|---|---|---|
| Platform token | dt0s16. | Authorization: Bearer <token> |
| Access token (classic API token) | dt0c01. | Authorization: Api-Token <token> |
| PaaS token | dt0s01. | Authorization: Bearer <token> |
| OAuth client secret | dt0s02. / dt0s03. | ❌ not directly usable — must be exchanged for a bearer token first |
Platform tokens are the forward-looking default. Dynatrace is deprecating access tokens: new tenants can no longer create them, and Classic API endpoints are being updated to accept platform tokens. Do not assume a token starts with dt0c01.. The reference implementation of this rule is dtwiz's AuthHeader() (pkg/installer/installer.go): dt0c01.* → Api-Token, everything else → Bearer.
One path hands the token to a component that has historically required a PaaS/access token — if it rejects a platform token, use a dt0c01. access token there:
- Kubernetes — the Dynatrace Operator authenticates using the
dynakubesecret.
VM, remote VM/EC2, Windows and Lambda call the Deployment API directly and work with either family.
Token scopes by target
For a platform token (dt0s16.), the OneAgent-relevant scopes live under Fleet management: fleet-management:oneagents:download, fleet-management:oneagent.connection-info:read, fleet-management:oneagent.tokens:read, fleet-management:cluster-id:read; Kubernetes additionally wants fleet-management:activegates:download and fleet-management:activegate.tokens:create. Generating the token via the Dynatrace QuickStart app provisions a working set.
For a classic access token (dt0c01.):
| Target | Required token scopes |
|---|---|
| VM / Windows | InstallerDownload (PaaS) |
| Kubernetes | InstallerDownload, settings.read, settings.write, activeGateTokenManagement.create — the Dynatrace UI's "Kubernetes: Dynatrace Operator" template sets all four. |
| Azure VM / VMSS | InstallerDownload (PaaS). Azure side: the caller's az identity needs Contributor or any role granting Microsoft.Compute/.../extensions/write on the resource. |
| AWS Lambda (runtime token) | A connection auth token consumed by the OneAgent layer at runtime. Distinct from the installer token. Create from the Dynatrace UI under Access tokens with entities.read, or use the Hub → AWS Lambda template. |
Tokens are never username-scoped — they belong to the tenant.
Targets
Each target has its own reference. They share the rules, URL normalization and token guidance above — read those first, then the one you need.
Managed Kubernetes distributions are covered inside the Kubernetes reference rather than separately: the install is identical and only the node type differs, so the deltas belong next to the procedure they modify.
| Target | Reference |
|---|---|
| VM / server (Linux, macOS) | below — the base case every other target builds on |
| Remote VM / EC2 over SSH | → references/remote-vm-ec2.md |
| Windows host (WSL or native) | → references/windows.md |
| Kubernetes (Operator + DynaKube) — incl. EKS, Fargate and Bottlerocket limits | → references/kubernetes.md |
| AWS Lambda (layer + env vars) | → references/aws-lambda.md |
| Azure VM / VM Scale Set (VM extension) | → references/azure-vm.md |
By platform
The table above is organised by install mechanism, because that is what decides the procedure. If you are arriving from a particular cloud instead:
| Platform | What you are deploying to | Go to |
|---|---|---|
| AWS | EC2 instance | remote-vm-ec2.md |
| EKS — EC2 nodes | kubernetes.md | |
| EKS — Fargate or Bottlerocket nodes | kubernetes.md § AWS EKS specifics — full-stack unavailable, applicationMonitoring only | |
| Lambda function | aws-lambda.md | |
| Azure | VM or VM Scale Set | azure-vm.md |
| AKS | kubernetes.md — not the VM extension, even though node pools are VMSSes | |
| Google Cloud | GKE (standard) | kubernetes.md |
| GKE Autopilot | kubernetes.md for the operator path — full-stack is unavailable, as on Bottlerocket. Autopilot-specific tuning is not covered | |
| Compute Engine VM | remote-vm-ec2.md — the SSH procedure is not AWS-specific | |
| On-prem / anywhere else | Linux or macOS you are logged into | below |
| Linux you reach over SSH | remote-vm-ec2.md | |
| Windows | windows.md | |
| Kubernetes, or OpenShift via the standard operator | kubernetes.md — the classic OpenShift node-config-operator route is not covered |
VM / server (Linux, macOS)
Endpoint (substitute ${DT_ENV_URL_NORMALIZED} and ${ARCH} where ARCH ∈ x86 | arm | ppc64le | s390):
GET ${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default
Header: Authorization: Api-Token ${DT_API_TOKEN} # dt0c01.… access token
Authorization: Bearer ${DT_API_TOKEN} # dt0s16.… platform token
Install command:
Set the scheme to match your token — Api-Token for dt0c01.…, Bearer for dt0s16.…:
DT_AUTH="Api-Token ${DT_API_TOKEN}" # platform token: DT_AUTH="Bearer ${DT_API_TOKEN}"
wget -O Dynatrace-OneAgent-Linux.sh \
--header="Authorization: ${DT_AUTH}" \
"${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default"
sudo /bin/sh Dynatrace-OneAgent-Linux.sh \
--set-monitoring-mode=fullstack \
--set-app-log-content-access=true \
[--set-host-group=<name>] \
[--set-network-zone=<zone>]
Restart caveat: OneAgent cannot inject into already-running processes. After install, restart the workloads you want monitored.
Uninstall:
sudo /opt/dynatrace/oneagent/agent/uninstall.sh
Removes the systemd unit, /opt/dynatrace, and the /etc/ld.so.preload line that injects the agent.
When you should not use this skill
- The user wants the install performed for them rather than explained. → This skill still applies: follow the target's procedure and run the commands, confirming the tenant first.
- The user is asking why an install failed and wants an explanation. → This skill is appropriate.
- The user wants a target this skill doesn't cover (Azure Functions / App Service / Container Apps, classic OpenShift node-config-operator, GKE Autopilot specifics, ECS Fargate). → Refer to https://docs.dynatrace.com; this skill covers VM/server, remote VM/EC2 over SSH, Windows, Kubernetes and AWS Lambda.
References
- OneAgent Linux install: https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/linux
- OneAgent Windows install: https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/windows
- Kubernetes (Operator + DynaKube): https://docs.dynatrace.com/docs/ingest-from/setup-on-k8s/deployment/full-stack-observability
- Dynatrace Operator releases: https://github.com/Dynatrace/dynatrace-operator/releases
- AWS Lambda (Hub): https://www.dynatrace.com/hub/detail/amazon-web-services-aws-lambda/
FAQ
What does the dt-setup-oneagent skill do?
Reference knowledge for installing, uninstalling, or creating-and-installing Dynatrace OneAgent across VM/server, Kubernetes (Operator + DynaKube), AWS Lambda (layer + env vars, plus optional fresh function provisioning), Windows hosts, remote Linux hosts / EC2 instances over SSH, and Azure VMs / VM Scale Sets. Returns documented endpoints, env vars, token scopes, and copy-paste-ready commands. Returns the exact commands to run rather than executing them. Use when the user asks to install or uninstall OneAgent, or asks "how do I…", "what URL/scope/var do I need for…", or "explain the OneAgent deployment for X".
How do I install dt-setup-oneagent?
Run npx skills add https://github.com/dynatrace/dynatrace-for-ai --skill dt-setup-oneagent in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dt-setup-oneagent/ (personal) or .claude/skills/dt-setup-oneagent/ (project).
Which AI agents can use dt-setup-oneagent?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dt-setup-oneagent safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains dt-setup-oneagent?
It is published by dynatrace in dynatrace/dynatrace-for-ai. It has 502 recorded installs.
More from dynatrace/dynatrace-for-ai
dt-dql-essentials
dynatrace/dynatrace-for-ai
Core DQL syntax, pitfalls, query patterns, and query optimization. Load to write, build, fix, or OPTIMIZE a DQL query — prevents syntax errors and makes queries faster, more efficient, and cheaper (less data scanned = lower query consumption/cost per run). Covers fetch commands, data models, field namespaces, time alignment, entity/smartscape patterns, metric discovery, and performance/cost optimization (filter early, bucket filters, short time ranges, field selection, sampling, cardinality). Trigger: "write/build/fix a DQL query", "DQL syntax", "query logs/spans/metrics", "create a timeseries", "optimize my DQL", "make my query faster/cheaper", "reduce DQL cost/consumption/scanned data", "keep DQL cost under control". Do NOT use to explain an existing query or answer product questions. For MONITORING a tenant's ACTUAL query consumption/billing (how much queries cost, who scanned most, cost trends) use dt-platform-costs — this tunes the query text, not billing data.
dt-app-dashboards
dynatrace/dynatrace-for-ai
Work with Dynatrace dashboards - create, modify, query, and analyze dashboard JSON including tiles, layouts, DQL queries, variables, and visualizations.
dt-obs-logs
dynatrace/dynatrace-for-ai
Log querying, filtering, pattern analysis, and error rate calculation. Use when searching application or infrastructure logs, analyzing error patterns, or correlating log data. Trigger: "show error logs", "search logs for keyword", "log error rate", "recent errors", "logs from last hour", "find log entries", "top error messages", "log patterns", "parse JSON logs", "logs by process group", "log trends over time", "log entry counts per minute". Do NOT use for explaining existing queries, product documentation questions, distributed tracing or span analysis (use dt-obs-tracing).
dt-obs-problems
dynatrace/dynatrace-for-ai
DAVIS problem analysis including root cause identification, impact assessment, and correlation with other telemetry. Use when querying or investigating detected problems. Trigger: "active problems", "root cause analysis", "problem impact", "affected users", "list problems", "P-12345 details", "recurring problems", "problem history", "problem trending", "blast radius", "which entity caused the problem", "problems affecting Kubernetes", "problems by service". Do NOT use for explaining existing queries, product documentation questions, generic log searching, distributed tracing, or host-level resource monitoring.
dt-app-notebooks
dynatrace/dynatrace-for-ai
Work with Dynatrace notebooks - create, modify, query, and analyze notebook JSON including sections, DQL queries, and visualizations.
dt-obs-tracing
dynatrace/dynatrace-for-ai
Distributed traces, spans, service dependencies, and request flow analysis. Use when investigating span-level details, failures, performance bottlenecks, or trace correlation. Trigger: "trace analysis", "slow requests", "failed spans", "service dependencies", "distributed trace", "span details", "HTTP status codes in traces", "database query spans", "messaging spans", "gRPC calls", "Lambda cold starts", "trace ID lookup", "exception analysis", "correlate logs and traces", "request attributes". Do NOT use for explaining existing queries, product documentation or configuration questions, service-level RED metrics (use dt-obs-services), log searching (use dt-obs-logs), or problem analysis (use dt-obs-problems).
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.