argocd-agent: an Argo CD control plane that agents call back into

The hub no longer opens connections to your clusters

Standard multi-cluster Argo CD assumes the control plane can reach a Kubernetes API server. That assumption breaks down across edge sites, factory floors and air-gapped networks, where inbound connections to a central server are blocked or unreliable. argocd-agent inverts that arrangement: each remote cluster runs a lightweight agent, and the agent dials the central Argo CD instance instead. The README describes the result as a hub-and-spoke layout in which the control plane needs no outbound connections to remote clusters, and each agent connects independently with no links between agents. Smart Sync then handles the data flow, since agents pull configuration and push status updates back automatically. The practical effect is that the network boundary moves to the direction that is usually open. For most enterprise networks, a workstation or a site agent can reach a central endpoint even when that endpoint cannot reach into the site.

Managed and autonomous clusters live in the same dashboard

The project offers two operating modes and expects you to mix them. In managed mode the control plane deploys applications to the remote cluster, which suits a fleet you want to roll out consistently, for example pushing the same configuration change to every store location. In autonomous mode the remote cluster runs its own applications through its own GitOps loop, and the control plane contributes observability and monitoring rather than deployment. The README positions autonomous mode as the answer for air-gapped or highly autonomous environments, where a central operator should not be able to push changes anyway. Because modes are chosen per cluster rather than per installation, one control plane can supervise a mixture: centrally managed clusters in one region, self-driving clusters in another, all visible in one dashboard. The cost of that flexibility is that the two modes expose different capabilities, so an operator has to know which clusters they can act on directly and which ones they can only observe.

Every agent connection is mutually authenticated

Security in this design rests on the agent side being the thing that authenticates, since the control plane has no way to reach back and challenge a cluster. The README lists mTLS on all communications, certificate-based authentication for every agent, and a zero-trust framing in which the control plane never needs direct cluster access. The dependency list backs that up: go.mod pulls in go-jose for certificate handling, golang-jwt for token work, SPIFFE support through spiffe/go-spiffe, gRPC with middleware, CloudEvents bindings for event delivery, and Redis for state. The repository also carries a principal/ directory and a proto/ directory, which points to an explicit identity and wire-format layer rather than improvised authentication inside the agent. Agents are also described as self-healing, reconnecting and recovering on their own, and as lightweight in resource use, which matters when the same image has to run on a device at the edge of a network with an unreliable link.

Building the agent image from the Dockerfile in the repository

The repository ships a multi-stage Dockerfile that compiles the Go binary in a builder image and copies it into a minimal runtime image. The builder stage pins the Go toolchain version and installs module dependencies before the source is copied, which keeps the dependency download layer cacheable:

FROM docker.io/library/golang:1.26.3 AS builder
WORKDIR /src

COPY go.mod go.sum ./
RUN go mod download

The compile step then runs the Makefile target for the binary:

RUN make argocd-agent

The runtime stage uses Alpine, upgrades the package index without keeping the cache, copies the finished binary from the builder and runs it as a non-root user with an entrypoint of /bin/argocd-agent. The Makefile holds the image coordinates, and the defaults are already multi-arch for both common Linux architectures:

IMAGE_REPOSITORY?=ghcr.io/argoproj-labs/argocd-agent
IMAGE_NAME=argocd-agent
IMAGE_TAG?=latest

The same Makefile names a second binary, argocd-agentctl, which is the CLI companion to the agent. The upstream documentation, hosted at argocd-agent.readthedocs.io, points operators to a Getting Started Guide, a Configuration Guide and an architecture page, and those pages carry the actual installation steps rather than the README.

Where the pull model stops paying off

Three limits are worth weighing before you commit. First, the transport is described as HTTP/1.1 compatible so it can pass through corporate proxies and legacy infrastructure, which is a deliberate downgrade from newer protocol behaviour and a hint about the environments this was built for. Second, resilience comes with latency: the README says agents work offline and sync when possible, so a broken link does not lose your deployment intent, but it does delay convergence and the dashboard shows stale state until the agent reconnects. Third, autonomous mode gives up the guarantee you actually want in some settings. If a remote cluster manages itself, the control plane cannot enforce a policy on it, and it can only report what the agent sends back, so an agent that is stopped or compromised silently removes that cluster from view rather than raising an error. The README does not document failover behaviour for the hub itself, which means a single control plane remains a single point of failure for the fleet view no matter how many agents run.

Observability tooling and network fault testing in the tree

The test dependencies reveal what the team worries about. go.mod includes Shopify/toxiproxy for injecting network faults, which is the right tool for testing reconnection behaviour under packet loss and latency, plus miniredis and redismock for the Redis-backed state without a real server, and go-cmp and testify for assertions. The examples/ directory ships agent-rbac/ and o11y/ directories, so RBAC and observability setups are given as working examples rather than prose. On the observability side the dependencies pull in the OpenTelemetry SDK with OTLP trace export, the Prometheus client, and gRPC instrumentation, matching the README claim of a unified view with health, sync status and metrics from every environment. That is a lot of machinery for a tool whose job is to make a phone-like agent on a remote link talk to a central server, which is the clearest signal that this is aimed at operators who already run Argo CD at scale rather than at a first-time cluster.

A v0.x project with quarterly-ish releases and an active roadmap

The release history is short but regular: v0.8.1 on 2026-04-08, v0.9.0 on 2026-06-04 and v0.10.0 on 2026-08-26. The last push was on 2026-10-20, two days before this write-up, and the project is not archived, so it is moving quickly. The version stays below 1.0, which is the honest signal that interfaces may still change, and the README itself points to GitHub milestones for current progress and to a ROADMAP.md file in the tree. Licensing is Apache-2.0, the same permissive terms many Argo CD components use, and the repository also carries SECURITY.md and CODEOWNERS, plus an integration test workflow in CI. Nothing in the documentation suggests the agent can be ignored during an Argo CD upgrade, so treat the agent and the control plane as a pair you upgrade together.

Editorial conclusion

Adopt argocd-agent when your clusters sit behind NAT, on site links that drop packets, or inside air-gapped networks, and when a single Argo CD control plane should still see them all. Do not adopt it if you need low latency to cluster state, if your compliance rules forbid a persistent outbound agent connection, or if you are looking for a stable 1.0 API, since the newest release is v0.10.0 and the interfaces are still moving. Verify first that your platform can run the linux/amd64 and linux/arm64 images published under ghcr.io/argoproj-labs/argocd-agent, that the cluster can open an outbound connection to the hub on HTTP/1.1, and that the RBAC example in examples/agent-rbac matches your own permissions model before you let agents run with cluster-wide rights.

Frequently asked questions

Official sources

1. argoproj-labs/argocd-agent on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases