Repository navigation
[BUG] Pinned Agent images | Ignoring --image-registry / --image-repository in private-registry deployments #2055
Description
📋 Prerequisites
- I have searched the existing issues to avoid creating a duplicate
- By submitting this issue, you agree to follow our Code of Conduct
- I am using the latest version of the software
- I have tried to clear cache/cookies or used incognito mode (if ui-related)
- I can consistently reproduce this issue
🎯 Affected Service(s)
Controller Service
🚦 Impact/Severity
Minor inconvenience
🐛 Bug Description
In >=v0.9.7, the controller pins declarative agent images using digests (registry/repository@sha256:...).
While the registry and repository are configurable at runtime via --image-registry and --image-repository, the digest itself is injected at controller link time from upstream images.
There is currently no runtime override for the digest, and --image-tag is silently ignored for declarative agents. As a result, in private/mirrored registry setups, the controller generates image references like:
my-registry.example.com/my-org/kagent/app@sha256:<UPSTREAM_DIGEST>
If the mirrored image does not retain the exact upstream manifest digest (e.g. due to rebuilds or recompression), all agent pods fail with: ImagePullBackOff / manifest unknown
🔄 Steps To Reproduce
- Prepare a private registry (e.g. ECR)
- Deploy the controller
- Create a declarative Agent
- Inspect the generated Deployment.
kubectl get deploy <agent-name> -o yaml
🤔 Expected Behavior
When --image-registry / --image-repository (Helm: agents.image.*) point to a private registry, the controller should emit an image reference that is resolvable in that registry, e.g.:
- honoring --image-tag, or
- allowing a runtime-provided digest that exists in the private registry
📱 Actual Behavior
- Image references are constructed using:
- runtime registry + repository
- link-time upstream digest
- --image-tag has no effect for declarative agents
Result: invalid image references in private registries
💻 Environment
- AWS EKS - eks.29
- Kubernetes - 1.33
- Kagent: 0.7.23
- Model: Bedrock - Anthropic Claude Sonnet 4.5
🔧 CLI Bug Report
No response
🔍 Additional Context
No response
📋 Logs
📷 Screenshots
No response
🙋 Are you willing to contribute?
- I am willing to submit a PR to fix this issue
Activity
igabi commentedon Jun 23, 2026
Opened #2076 to address this. It adds an opt-in
--pin-runtime-image-digestflag (envPIN_RUNTIME_IMAGE_DIGEST, Helmcontroller.pinRuntimeImageDigest), defaulting totrueto keep today's digest pinning. Setting it tofalsemakes the Python/Go runtime resolvers emit a tag reference (registry/repository:tag) that is resolvable in private registries that don't preserve the upstream manifest digest. Covered by Go and Helm unit tests.anthonyhaussman commentedon Jul 6, 2026
I'm facing the same issue. 🥹
iplay88keys commentedon Jul 15, 2026
I have a fix for this here.
Reference declarative agents by tag; digests only for sandbox agents (#…
iplay88keys commentedon Jul 15, 2026
Backported to 0.9.x here.
Backport(0.9.x): reference declarative agents by tag; digests only fo…
acherifi commentedon Jul 28, 2026
Following up on this: #2242 covered tag-based resolution for regular declarative agents plus digest-override flags for the app/golang runtime images, but the Substrate ACP sandbox workload images (acp-sandbox-hermes / acp-sandbox-openclaw) are still pinned to link-time digests with no override — which blocks serving them from a private/air-gapped registry mirror. I have a small follow-up ready that adds the two missing controller flags plus Helm values plumbing for all six digest overrides; opening the PR now. Happy to adjust the values layout if maintainers prefer these nested differently.