Decision: One resolution order for every credential

Status: implemented Implemented: 2026-09-30 Related: 2026-09-30-unified-config-keys.md, 2026-09-29-region-command-level-option.md, 2026-09-29-config-init-wizard.md, 2026-09-02-dual-auth-mode.md

Problem

A credential could be set in a function argument, a process environment variable, ./.env, and ~/.abx, and each caller picked a different winner. Sandbox.create stopped at the first .env file it found, so a project file that did not contain the sandbox key hid ~/.abx/.env. Sandbox.deploy never read ~/.abx at all. abx config list ignored ./.env and ignored vendor LLM variables when a stored llm_api_key existed. abx mcp install parsed ~/.abx/.env by hand and could return SANDBOX_API_KEY ahead of E2B_API_KEY. Public docs also disagreed: getting started listed the code parameter as the lowest priority, and the region notes wrote abx config set region and SANDBOX_REGION as one tier.

Decision

Every credential is resolved in one order. The first non-blank value wins:

1. Explicit argument for this call (api_key=, llm_api_key=, openai_base_url=, openai_model=, --token, command --region).
2. Process environment, in the per-key order below.
3. ./.env, same names.
4. ~/.abx: secrets in ~/.abx/.env (abx config set), endpoint / model / region in ~/.abx/config.toml.
5. Built-in default, or unset when the key has none.

.env files merge per key. ./.env overrides ~/.abx/.env only for a key it sets. A key the project file omits still comes from ~/.abx/.env. A blank or whitespace-only value is unset and does not hide the next layer.

abx config list labels the winner (env) for the process environment, (user) for either file, (default) for a built-in default, and (not set) when nothing applies. Secrets stay masked.

Callers that share this order:

• Sandbox.create and the other SDK clients go through agent_sandbox.transport.config.load_config. agent_sandbox.api.sandbox._build_infra passes that result into create_auth_provider. The auth helper does not walk ~/.abx itself.
• Sandbox.deploy uses agent_sandbox.api.deploy.resolve_llm_env. api/deploy.py does not import the CLI.
• Natural-language abx create uses resolve_coding_agent_credentials, which calls config_cmd._effective_value and then passes the winner into resolve_qwen_code_credentials as stored_api_key. That lower function treats the argument as already chosen.
• abx template install / abx template search use resolve_github_token (--token is the explicit layer).
• abx mcp install copies the sandbox key from load_config().api_key. The api_url and region it embeds into the editor config are still taken only from the process environment; the later abx mcp start process loads config again.
• resolve_region and every regional command use load_config, so SANDBOX_REGION beats abx config set region.

The user-facing copy of this table is Credential resolution and 凭证解析.

API Design

load_config(**overrides) -> TransportConfig
    overrides > process env > merged .env files > ~/.abx/config.toml > defaults

project_dotenv_value(names: tuple[str, ...]) -> str | None
    first non-blank name in ./.env only

resolve_llm_env(*, llm_api_key, openai_base_url, openai_model) -> dict[str, str]
    explicit > process env > ./.env > ~/.abx > DashScope default
    raises DeployLLMKeyMissingError (E7001) when no key exists

resolve_github_token(explicit: str | None) -> str | None
    --token > process GITHUB_TOKEN > ./.env > ~/.abx/.env > None

_effective_value(key) -> (value, "env" | "user" | "default" | "unset")

TransportConfig.api_key and Sandbox.create(api_key=) stay. The CLI name is sandbox_api_key.

Alternatives considered

• Process environment only, with ~/.abx as a write-only store. Rejected: a developer who ran abx config set and then opened a new shell with no exports would appear to have no key.
• ~/.abx beats the process environment. Rejected: CI and a one-off export must be able to override the machine store without editing it.
• First existing .env file wins as a whole. Rejected: a project .env used for unrelated tools hid the sandbox key stored in ~/.abx/.env.
• A new (project) source label in abx config list. Rejected: both files are user configuration. (env) stays reserved for the process environment so the label still answers "will this shell override the files?"
• Teach resolve_qwen_code_credentials to re-read the environment after it receives stored_api_key. Rejected: the CLI already resolved the winner. A second pass would let a vendor variable override an explicit stored argument that a direct caller passed on purpose.

Dependencies

agent_sandbox.transport.config, agent_sandbox.cli.commands.config_cmd, agent_sandbox.api.deploy, agent_sandbox.cli.commands._coding_agent, agent_sandbox.cli.commands.mcp, agent_sandbox.cli.region. python-dotenv reads the .env files. Deploy must not import the CLI.

Test Strategy

tests/integration/test_credential_priority_e2e.py points the CLI, load_config, resolve_llm_env, the coding agent, resolve_github_token, resolve_region, MCP's editor-config writer, and ACR namespace resolution at one temporary home and one project .env. It checks the process environment beating both files, a project file that omits a key still yielding ~/.abx, and a key set in ./.env beating ~/.abx and losing to the process environment. It also checks same-layer order (E2B_API_KEY over SANDBOX_API_KEY, ABX_LLM_API_KEY over DASHSCOPE_API_KEY, ALICLOUD_ACCESS_KEY_ID over AccessKey), a command --region beating SANDBOX_REGION, a blank value falling through, a legacy ABX_QWEN_CODE_API_KEY, and --acr-namespace over ACR_NAMESPACE over ./.env over ~/.abx. An explicit llm_api_key= and --token still win. MCP copies SANDBOX_REGION into the editor config only when the process environment sets it.

tests/test_transport/test_config.py covers the per-key .env merge. tests/test_cli/test_config_commands.py covers a whitespace GITHUB_TOKEN falling through to the stored token. tests/test_cli/test_region_options.py already asserts SANDBOX_REGION beats config.toml.

The suite isolates transport.config._PROJECT_ENV_FILE so a developer's ./.env cannot leak into abx config list.

Acceptance criteria

• With E2B_API_KEY exported and a different key in ~/.abx/.env, abx config list, load_config().api_key, and abx mcp install all use the exported key.
• With neither the process environment nor ./.env setting ABX_LLM_API_KEY, Sandbox.deploy and natural-language abx create use the key stored by abx config set llm_api_key.
• A ./.env that sets only SANDBOX_HTTP_TIMEOUT does not hide E2B_API_KEY in ~/.abx/.env.
• DASHSCOPE_API_KEY in the process environment beats a stored llm_api_key. ABX_LLM_API_KEY beats DASHSCOPE_API_KEY.
• SANDBOX_REGION beats region in ~/.abx/config.toml. A command --region beats both.
• A whitespace-only GITHUB_TOKEN does not hide the stored token.