[aheritier]

Closes #4702

Summary

docker-agent shares variable names with other tools: Claude Code reads ANTHROPIC_API_KEY, Codex reads OPENAI_API_KEY. Exporting ANTHROPIC_API_KEY="op://…" to benefit from 1Password references breaks those tools, which do not resolve op://.

docker-agent now looks up DOCKER_AGENT_ENV_<NAME> before <NAME>:

export ANTHROPIC_API_KEY=sk-ant-...                                         # other tools
export DOCKER_AGENT_ENV_ANTHROPIC_API_KEY="op://Personal/Anthropic/api-key" # docker-agent

Changes

• pkg/environment: PrefixedProvider and LookupNames; a single NewChain constructor (OnePassword(Prefixed(Multi(...)))) used by NewDefaultProvider and by --env-from-file in pkg/config/runtime.go.
• docker agent doctor: its lookup env honours the override (auto-selection, agent-file checks), findSource mirrors the run-time order, and the name found is reported as a new optional found_as JSON field; env_var stays the canonical name.
• Secrets guide: "Docker Agent-only variables" subsection.

Behavior decisions

1. Prefix DOCKER_AGENT_ENV_, not DOCKER_AGENT_. DOCKER_AGENT_ is docker-agent's settings namespace (DOCKER_AGENT_REMOTE_AUTH_TOKEN, DOCKER_AGENT_ENCRYPT_KEY, DOCKER_AGENT_DATA_DIR, …). With a bare DOCKER_AGENT_ prefix, an MCP ${REMOTE_AUTH_TOKEN} would resolve to docker-agent's own token. Names already in DOCKER_AGENT_ are never looked up as overrides.
2. Precedence: the override wins across the whole chain, --env-from-file included.
3. Empty override falls back to <NAME>, so a blank line or export X= cannot hide a valid key. Doctor and the runtime agree on this.

Side effect: op:// values in --env-from-file were not resolved before (env files sat outside the 1Password wrapper, although the docs said they were); they are now.

Out of scope

• The TUI transcriber reads OPENAI_API_KEY with os.Getenv, bypassing the chain. Fixing it needs lazy resolution in pkg/audio/transcribe to avoid an op prompt on every TUI launch; follow-up PR. Documented.
• Keys injected by the --sandbox proxy are not read through the chain; documented.

Tests

• PrefixedProvider table test asserting value and names looked up, including the settings-namespace case that would have leaked.
• NewDefaultProvider and RuntimeConfig.EnvProvider: overrides span the default chain and --env-from-file in both directions.
• doctor: auto-selection with only the override set and DMR down (mutation-checked), JSON env_var/found_as, agent-file requirements, findSource precedence and empty-override fallback.

References

Topic	Link
Feature issue	#4702
Default secret chain	pkg/environment/default.go
--env-from-file chain	pkg/config/runtime.go (computedEnvProvider)
1Password resolution	pkg/environment/onepassword.go, 1Password CLI op read
Sandbox env forwarding	pkg/sandbox/sandbox.go (EnvForSource, proxyManagedEnvVars)
Secrets guide	docs/guides/secrets/index.md
Related	#4701 (docs), #4703 (credential helper for all secrets)

---

This is part 1 of 2 in a stack made with GitButler:

•  2  fix(tui): resolve the /speak OpenAI key through the secret chain #4709
•  1  feat: read DOCKER_AGENT_ENV_-prefixed secret variables #4708 👈

[Copilot]

🟡 Changes recommended

Doctor can report an available credential that runtime ignores when a higher-priority source contains an empty override.

1 open issue

• Doctor ignores empty higher-priority credential overrides · New

What changed in this PR

Adds Docker Agent-specific secret overrides so users can keep separate credentials or 1Password references without affecting other tools that share the standard environment variable names.

Changes:

• Introduces DOCKER_AGENT_ENV_ lookup precedence across default sources and --env-from-file.
• Updates doctor to recognize overrides and report their names through found_as.
• Adds precedence tests and documents usage, empty-value fallback, and limitations.

File	Description
pkg/​environment/​prefixed.go	Adds override lookup with settings-namespace protection.
pkg/​environment/​prefixed_test.go	Tests precedence, fallback, and namespace isolation.
pkg/​environment/​default.go	Centralizes override and 1Password provider composition.
pkg/​environment/​default_test.go	Tests override precedence across default sources.
pkg/​config/​runtime.go	Includes explicit env files in the shared secret chain.
pkg/​config/​runtime_test.go	Tests precedence between env files and default sources.
docs/​guides/​secrets/​index.md	Documents overrides and transcription/sandbox limitations.
cmd/​root/​doctor.go	Recognizes overrides and reports credential source names.
cmd/​root/​doctor_test.go	Tests doctor selection, reporting, and override lookup.

_{Review effort: Balanced}

[aheritier]

Good catch, fixed in fff6189, but on the runtime side rather than in doctor: the docs say an empty override is ignored, so the empty shell value should not hide the env-file override. PrefixedProvider now takes the sources and skips empty overrides source by source, which is what findSource already did. --env-from-file goes through the same NewChain, so it is covered too.

Regression tests: TestPrefixedProvider_EmptyOverrideDoesNotHideLaterSources (runtime) and TestFindSource_EmptyOverrideDoesNotHideLaterOverride, which also asserts doctor and the run-time chain agree.

[aheritier]

👋 Some commits in this PR are not signed and verified by GitHub. Please sign your commits with a GPG or SSH key registered in your GitHub account, then force-push.\n\nCommits that are not verified: 5283a4f, 3804510, a23c44e\n\nSee GitHub\x27s guide on signing commits for setup instructions. I\x27ve added status/needs-signed-commits; it will be removed automatically once every commit in this PR carries a valid GitHub-verified signature.