Skip to main content
The Odigos VM Agent is available as part of Odigos Pro. For access and licensing details, contact us.
The Odigos ECS Agent is the same agent as the VM Agent, packaged as a container image and deployed as an ECS daemon service — one agent task on every EC2 container instance in the cluster. Each agent discovers the ECS tasks running on its instance through the instance’s Docker daemon, instruments them in place with eBPF, and runs the odigos-otelcol collector as a supervised child process to export the telemetry.
Instrumentation is direct attach only: the agent never restarts, recreates, or modifies your task definitions. Deploying Odigos does not redeploy your services.

​
How it works

One agent per container instance, repeated across every instance in the cluster. Each agent connects upstream either directly to Central (single node) or through the proxy (multi node) — see Choose a deployment mode below.
  • Discovery — the agent reads the instance’s Docker socket to map processes to ECS tasks, services, and task ARNs. Only ECS-managed containers are instrumented; host processes and systemd services on the container instance are ignored (unlike the VM Agent and Docker deployment).
  • Instrumentation — Java, Go, and C++ attach through their dynamic eBPF SDKs. Every other language is covered by OBI, which also attaches with no restart. Restart-based instrumentation (Python/Node.js/.NET environment injection) is intentionally not used on ECS, since ECS owns the container lifecycle.
  • Export — the collector runs inside the agent container with host networking, so instrumented tasks reach it on the instance’s network namespace.
  • Configuration — the task definition only bootstraps the agent (Central or proxy endpoint, license). Sources, destinations, actions, and instrumentation rules are managed from Odigos Central or with odictl, exactly as on any VM Agent. On ECS, odictl runs inside the agent container over ECS Exec.

​
Choose a deployment mode

Both modes run the same agent daemon and instrument workloads identically. The difference is how the cluster appears in Odigos Central and whether you deploy one extra component. Select your cluster shape for the installation flow:
One container instance — the agent alone is all you need.The agent daemon runs on the instance and connects straight to Odigos Central, which shows the cluster as a single platform named after it. No proxy, no load balancer, no extra AWS resources.
1

Store the license token

AWS Secrets Manager (or a plain env var for a test cluster).
2

Create two IAM roles

Task execution role, plus a task role for odictl over ECS Exec.
3

Register the agent task definition

Privileged, pidMode: host, host networking, with your Central endpoint in ODIGOS_DEFAULT_CONFIG.
4

Create the DAEMON service

One agent task per container instance, now and for instances that join later.
5

Verify

Kernel 5.10+, agent connected, platform visible in Central.

Install: Single Node

Follow the full Agent-only flow.
This flow also works unchanged on a multi-node cluster — you simply get one platform per node instead of one per cluster. Choose it whenever you don’t need cluster-wide aggregation.
Not sure? Start single node. The flow is identical on a 1-node or a 50-node cluster, and moving to Agent + Proxy later is just re-pointing the agents’ endpoint at the proxy and rolling the daemon service — no reinstall. See Switch to Multi Node.

​
What the proxy adds

odigos-ecs-proxy is the ECS counterpart of the Kubernetes central-proxy: one task per cluster that represents the whole cluster to Odigos Central as a single compute platform.
  • Request routing — configuration queries go to any one healthy agent (the config is identical on all of them); live state such as workload reports fans out to every agent and is merged; configuration changes are broadcast to all agents.
  • Config journal — configuration changes are recorded, so a node that joins the cluster later (or a task that migrates to a fresh instance) converges to the cluster configuration automatically.
  • Membership and coverage — GET /healthz lists the connected agents, departed nodes, and — when coverage checking is enabled — ACTIVE container instances that have no agent connected.
The proxy is unprivileged: no host PID, no Docker socket, no host mounts.

​
Not supported: Fargate

The ECS Agent requires the EC2 launch type. It needs host PID access, the instance’s Docker socket, and the ability to load eBPF programs — none of which exist on Fargate, where AWS controls the host. There is no Fargate deployment mode.

​
Next steps

System Requirements

Launch type, kernel and AMI requirements, IAM, and images.

Install: Single Node

Agent only — daemon service, direct to Central.

Install: Multi Node

Agent + Proxy — one platform per cluster, with aggregation and config replay.

Configuration Reference

Every environment variable, platform naming, and where configuration is persisted.