Merge pull request #3713 from dgageot/remove-keychain-pass-env-providers

feat(env): remove macOS keychain and pass secret providers

Author: dgageot

cmd/root/doctor.go

@@ -98,8 +98,8 @@ type doctorFlags struct {
 
 	// Test seams: sourcesForTests replaces the env-file + default secret-source
 	// chain, dmrLister replaces dmr.ListModels, and loadUserConfig replaces
-	// userconfig.Load so tests never exec `pass`/`security`/`docker model` or
-	// read the developer's real configuration.
+	// userconfig.Load so tests never exec `docker model` or credential helpers,
+	// and never read the developer's real configuration.
 	sourcesForTests []environment.Source
 	dmrLister       config.DMRModelLister
 	loadUserConfig  userConfigLoader

cmd/root/doctor_test.go

@@ -21,7 +21,7 @@ import (
 
 // withDoctorTestEnv wires a hermetic doctor command: a map-backed secret
 // source chain, a stubbed DMR lister, and an empty user config, so tests
-// never exec `pass`/`security`/`docker model` and never read the developer's
+// never exec `docker model` or credential helpers and never read the developer's
 // real configuration.
 func withDoctorTestEnv(env map[string]string, dmrModels []string, dmrErr error) doctorCmdOption {
 	return func(f *doctorFlags) {

cmd/root/models.go

@@ -58,7 +58,7 @@ type modelRow struct {
 // modelsCmdOption pre-seeds the RuntimeConfig backing the models command
 // before its flags are wired. It is the seam tests use to inject a hermetic
 // env provider and an in-memory models.dev store, so listing models never
-// shells out to the OS keychain or reaches the network. Production calls
+// shells out to secret helper CLIs or reaches the network. Production calls
 // newModelsCmd with no options, leaving behavior unchanged.
 type modelsCmdOption func(*config.RuntimeConfig)
 

cmd/root/models_test.go

@@ -53,7 +53,7 @@ func testCatalog() *modelsdev.Database {
 
 // withTestConfig injects a hermetic env provider and an in-memory models.dev
 // store into the models command. It keeps listing side-effect-free: without it
-// the real env provider chain shells out to the OS keychain / pass / 1Password
+// the real env provider chain consults Docker Desktop / 1Password
 // for every missing API key and the store fetches https://models.dev, making
 // the tests slow and non-parallelizable.
 func withTestConfig(env map[string]string) modelsCmdOption {

cmd/root/setup.go

@@ -53,7 +53,7 @@ type setupResult struct {
 }
 
 // setupWizard drives the interactive model setup. The function fields are
-// seams: production wiring talks to the terminal, the OS secret stores, and
+// seams: production wiring talks to the terminal, the secret stores, and
 // Docker Model Runner, while tests inject scripted answers and fakes.
 //
 // in is buffered once at construction: a fresh bufio.Reader per prompt would
@@ -78,18 +78,17 @@ func newSetupCmd() *cobra.Command {
 		Long: `Set up a model for docker agent, interactively.
 
 Three paths:
-  - Cloud provider: pick a provider, paste its API key, and choose where to
-    store it (OS keychain, pass, or the docker agent env file). Picking
-    chatgpt signs in with your ChatGPT account in the browser instead of
-    asking for an API key.
+  - Cloud provider: pick a provider, paste its API key, and store it in the
+    docker agent env file (~/.config/cagent/.env). Picking chatgpt signs in
+    with your ChatGPT account in the browser instead of asking for an API key.
   - Local model: check Docker Model Runner and pull a model. No API key needed.
   - OpenAI-compatible provider: register a custom endpoint (vLLM, LiteLLM,
     a corporate gateway, ...) with its API format and API key variable. The
     provider is saved to your user configuration and its models become
     usable everywhere via --model <name>/<model>.
 
-Ends with the exact command to start chatting. Secret values are stored where
-you choose and never printed. Check the result anytime with 'docker agent doctor'.`,
+Ends with the exact command to start chatting. Secret values are never
+printed. Check the result anytime with 'docker agent doctor'.`,
 		Example:      `  docker-agent setup`,
 		GroupID:      "core",
 		Args:         cobra.NoArgs,
@@ -181,7 +180,7 @@ func (w *setupWizard) run(ctx context.Context) (*setupResult, error) {
 }
 
 // setupCloudProvider walks the cloud path: pick a provider, paste its key,
-// pick a store, and persist the key there.
+// and persist it in a secret store.
 func (w *setupWizard) setupCloudProvider(ctx context.Context) (*setupResult, error) {
 	providers := config.CloudProviderEnvVars()
 
@@ -247,24 +246,33 @@ func (w *setupWizard) promptSecret(ctx context.Context, prompt string) (string,
 	}
 }
 
-// storeSecret asks where to store the key and persists it, re-asking when a
-// store fails (e.g. an uninitialized pass store) so the pasted key is not
-// lost to a storage hiccup.
+// storeSecret persists the key in a secret store. When several stores are
+// available it asks which one to use, re-asking when a store fails so the
+// pasted key is not lost to a storage hiccup.
 func (w *setupWizard) storeSecret(ctx context.Context, envVar, key string) error {
+	if len(w.stores) == 0 {
+		return errors.New("no secret store is available to save the key")
+	}
 	for {
-		fmt.Fprintln(w.out)
-		fmt.Fprintf(w.out, "Where should %s be stored?\n", envVar)
-		for i, store := range w.stores {
-			fmt.Fprintf(w.out, "  %d. %s\n", i+1, store.Description())
-		}
+		store := w.stores[0]
+		if len(w.stores) > 1 {
+			fmt.Fprintln(w.out)
+			fmt.Fprintf(w.out, "Where should %s be stored?\n", envVar)
+			for i, s := range w.stores {
+				fmt.Fprintf(w.out, "  %d. %s\n", i+1, s.Description())
+			}
 
-		choice, err := w.promptChoice(ctx, len(w.stores), 1)
-		if err != nil {
-			return err
+			choice, err := w.promptChoice(ctx, len(w.stores), 1)
+			if err != nil {
+				return err
+			}
+			store = w.stores[choice-1]
 		}
-		store := w.stores[choice-1]
 
 		if err := store.Store(ctx, envVar, key); err != nil {
+			if len(w.stores) == 1 {
+				return fmt.Errorf("storing the key: %w", err)
+			}
 			fmt.Fprintf(w.out, "Could not store the key: %v\nPick another location, or press Ctrl+C to cancel.\n", err)
 			continue
 		}
@@ -654,9 +662,8 @@ func (f *runExecFlags) offerSetupOnNoModel(ctx context.Context, cmd *cobra.Comma
 	}
 
 	// The run's env provider chain was built before the wizard stored the key,
-	// so bridge it into the process environment for the retry. Keychain and
-	// pass lookups are live either way; the config env file is not, when it
-	// did not exist at chain construction.
+	// so bridge it into the process environment for the retry: the config env
+	// file is not live when it did not exist at chain construction.
 	if result.EnvVar != "" {
 		if err := os.Setenv(result.EnvVar, result.Value); err != nil {
 			slog.WarnContext(ctx, "Failed to export the stored key for the retry", "env_var", result.EnvVar, "error", err)

cmd/root/setup_test.go

@@ -77,9 +77,9 @@ func newTestWizard(answers string, keys []string, stores []environment.SecretSto
 func TestSetupWizard_CloudPathStoresKey(t *testing.T) {
 	t.Parallel()
 
-	store := &fakeSecretStore{name: "keychain"}
-	// cloud -> provider 1 (anthropic) -> store 1
-	wizard, out, _ := newTestWizard("1\n1\n1\n", []string{"sk-cloud-key"}, []environment.SecretStore{store}, nil, nil)
+	store := &fakeSecretStore{name: "config-env-file"}
+	// cloud -> provider 1 (anthropic); a single store is used without a prompt
+	wizard, out, _ := newTestWizard("1\n1\n", []string{"sk-cloud-key"}, []environment.SecretStore{store}, nil, nil)
 
 	result, err := wizard.run(t.Context())
 	require.NoError(t, err)
@@ -90,7 +90,8 @@ func TestSetupWizard_CloudPathStoresKey(t *testing.T) {
 	assert.Equal(t, "anthropic/claude-sonnet-4-6", result.Model)
 
 	output := out.String()
-	assert.Contains(t, output, "Stored ANTHROPIC_API_KEY in the keychain (fake).")
+	assert.NotContains(t, output, "Where should", "a single store must not prompt for a location")
+	assert.Contains(t, output, "Stored ANTHROPIC_API_KEY in the config-env-file (fake).")
 	assert.Contains(t, output, "docker agent run")
 	assert.Contains(t, output, "--model anthropic/claude-sonnet-4-6")
 	assert.Contains(t, output, "docker agent doctor")
@@ -100,9 +101,9 @@ func TestSetupWizard_CloudPathStoresKey(t *testing.T) {
 func TestSetupWizard_DefaultsSelectCloudAndFirstEntries(t *testing.T) {
 	t.Parallel()
 
-	store := &fakeSecretStore{name: "keychain"}
-	// Empty answers take every default: cloud, first provider, first store.
-	wizard, _, _ := newTestWizard("\n\n\n", []string{"sk-key"}, []environment.SecretStore{store}, nil, nil)
+	store := &fakeSecretStore{name: "config-env-file"}
+	// Empty answers take every default: cloud, first provider.
+	wizard, _, _ := newTestWizard("\n\n", []string{"sk-key"}, []environment.SecretStore{store}, nil, nil)
 
 	result, err := wizard.run(t.Context())
 	require.NoError(t, err)
@@ -115,7 +116,7 @@ func TestSetupWizard_DefaultsSelectCloudAndFirstEntries(t *testing.T) {
 func TestSetupWizard_CloudPathRetriesFailedStore(t *testing.T) {
 	t.Parallel()
 
-	broken := &fakeSecretStore{name: "pass", err: errors.New("password store is empty")}
+	broken := &fakeSecretStore{name: "broken-store", err: errors.New("store is unavailable")}
 	working := &fakeSecretStore{name: "config-env-file"}
 	// cloud -> provider 1 -> store 1 (fails) -> store 2 (succeeds)
 	wizard, out, _ := newTestWizard("1\n1\n1\n2\n", []string{"sk-key"},
@@ -124,15 +125,37 @@ func TestSetupWizard_CloudPathRetriesFailedStore(t *testing.T) {
 	result, err := wizard.run(t.Context())
 	require.NoError(t, err)
 
-	assert.Contains(t, out.String(), "Could not store the key: password store is empty")
+	assert.Contains(t, out.String(), "Could not store the key: store is unavailable")
 	assert.Equal(t, "sk-key", working.stored[result.EnvVar])
 }
 
+func TestSetupWizard_CloudPathSingleStoreFailureIsFatal(t *testing.T) {
+	t.Parallel()
+
+	broken := &fakeSecretStore{name: "config-env-file", err: errors.New("disk full")}
+	wizard, _, _ := newTestWizard("1\n1\n", []string{"sk-key"}, []environment.SecretStore{broken}, nil, nil)
+
+	_, err := wizard.run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "storing the key")
+	assert.Contains(t, err.Error(), "disk full")
+}
+
+func TestSetupWizard_CloudPathNoStoresIsFatal(t *testing.T) {
+	t.Parallel()
+
+	wizard, _, _ := newTestWizard("1\n1\n", []string{"sk-key"}, nil, nil, nil)
+
+	_, err := wizard.run(t.Context())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "no secret store is available")
+}
+
 func TestSetupWizard_CloudPathReasksOnEmptyKey(t *testing.T) {
 	t.Parallel()
 
-	store := &fakeSecretStore{name: "keychain"}
-	wizard, out, _ := newTestWizard("1\n1\n1\n", []string{"  ", "sk-key"}, []environment.SecretStore{store}, nil, nil)
+	store := &fakeSecretStore{name: "config-env-file"}
+	wizard, out, _ := newTestWizard("1\n1\n", []string{"  ", "sk-key"}, []environment.SecretStore{store}, nil, nil)
 
 	_, err := wizard.run(t.Context())
 	require.NoError(t, err)
@@ -148,8 +171,8 @@ func TestSetupWizard_ChatGPTPathRunsBrowserSignIn(t *testing.T) {
 	idx := slices.IndexFunc(providers, func(p config.ProviderEnvVars) bool { return p.Provider == "chatgpt" })
 	require.GreaterOrEqual(t, idx, 0, "chatgpt must be offered by the wizard")
 
-	store := &fakeSecretStore{name: "keychain"}
-	// cloud -> chatgpt: no key prompt, no store prompt.
+	store := &fakeSecretStore{name: "config-env-file"}
+	// cloud -> chatgpt: no key prompt, no store involved.
 	wizard, out, _ := newTestWizard(fmt.Sprintf("1\n%d\n", idx+1), nil, []environment.SecretStore{store}, nil, nil)
 	loginCalled := false
 	wizard.chatgptLogin = func(_ context.Context, _ io.Writer) (*chatgpt.LoginResult, error) {
@@ -274,10 +297,10 @@ func (r *customProviderRecorder) save(name string, provider latest.ProviderConfi
 func TestSetupWizard_CustomPathSavesProviderAndKey(t *testing.T) {
 	t.Parallel()
 
-	store := &fakeSecretStore{name: "keychain"}
+	store := &fakeSecretStore{name: "config-env-file"}
 	recorder := &customProviderRecorder{}
-	// custom -> name -> base URL -> format 2 (responses) -> env var -> store 1 -> model (default)
-	wizard, out, _ := newTestWizard("3\nmyprovider\nhttps://llm.corp.example.com/v1\n2\nMYPROVIDER_API_KEY\n1\n\n",
+	// custom -> name -> base URL -> format 2 (responses) -> env var -> model (default)
+	wizard, out, _ := newTestWizard("3\nmyprovider\nhttps://llm.corp.example.com/v1\n2\nMYPROVIDER_API_KEY\n\n",
 		[]string{"sk-custom-key"}, []environment.SecretStore{store}, nil, nil)
 	wizard.saveProvider = recorder.save
 	wizard.listModels = func(_ context.Context, baseURL, token string) []string {
@@ -362,9 +385,9 @@ func TestSetupWizard_CustomPathValidatesNameAndURL(t *testing.T) {
 func TestSetupWizard_CustomPathReasksOnInvalidEnvVarName(t *testing.T) {
 	t.Parallel()
 
-	store := &fakeSecretStore{name: "keychain"}
+	store := &fakeSecretStore{name: "config-env-file"}
 	recorder := &customProviderRecorder{}
-	wizard, out, _ := newTestWizard("3\nmyprovider\nhttps://ok.example.com/v1\n1\nMY BAD VAR\nMY_KEY\n1\nm1\n",
+	wizard, out, _ := newTestWizard("3\nmyprovider\nhttps://ok.example.com/v1\n1\nMY BAD VAR\nMY_KEY\nm1\n",
 		[]string{"sk-key"}, []environment.SecretStore{store}, nil, nil)
 	wizard.saveProvider = recorder.save
 

docs/community/troubleshooting/index.md

@@ -60,10 +60,9 @@ The following environment variables must be set:
  - ANTHROPIC_API_KEY
 
 Provide them using any of these sources:
- - Shell environment:  export ANTHROPIC_API_KEY=<value>
- - Env file:           docker agent run --env-from-file <file> ...
- - pass:               pass insert ANTHROPIC_API_KEY
- - macOS Keychain:     security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w
+ - Shell environment:      export ANTHROPIC_API_KEY=<value>
+ - Env file:               docker agent run --env-from-file <file> ...
+ - Docker Agent env file:  docker agent setup (stores the key in ~/.config/cagent/.env)
 
 See https://docs.docker.com/ai/docker-agent/guides/secrets/ for details.
 ```

docs/configuration/overview/index.md

@@ -129,7 +129,7 @@ Models can be referenced inline or defined in the `models` section:
 
 ## Environment Variables
 
-API keys and secrets are read from environment variables — never stored in config files. See [Managing Secrets](../../guides/secrets/index.md) for all the ways to provide credentials (env files, Docker Compose secrets, macOS Keychain, `pass`):
+API keys and secrets are read from environment variables — never stored in config files. See [Managing Secrets](../../guides/secrets/index.md) for all the ways to provide credentials (env files, Docker Compose secrets, the Docker Agent env file):
 
 | Variable                   | Provider                                            |
 | -------------------------- | --------------------------------------------------- |

docs/features/cli/index.md

@@ -229,7 +229,7 @@ $ docker agent toolsets --format json | jq             # machine-readable (type,
 
 ### `docker agent setup`
 
-Set up a model interactively. Three paths: pick a cloud provider, paste its API key, and choose where to store it (macOS Keychain, `pass`, or the Docker Agent env file `~/.config/cagent/.env`); check Docker Model Runner and pull a local model (no API key needed); or register a custom OpenAI-compatible provider (endpoint URL, API format, and API key variable) saved to your [user configuration](../../providers/custom/index.md#global-providers-user-configuration) so its models work everywhere via `--model <name>/<model>`. Ends with the exact command to start chatting. Secret values are never printed.
+Set up a model interactively. Three paths: pick a cloud provider, paste its API key, and store it in the Docker Agent env file `~/.config/cagent/.env`; check Docker Model Runner and pull a local model (no API key needed); or register a custom OpenAI-compatible provider (endpoint URL, API format, and API key variable) saved to your [user configuration](../../providers/custom/index.md#global-providers-user-configuration) so its models work everywhere via `--model <name>/<model>`. Ends with the exact command to start chatting. Secret values are never printed.
 
 The wizard is also offered automatically when an interactive run finds no usable model (decline-able; set `DOCKER_AGENT_NO_SETUP=1` to suppress the offer).
 
@@ -239,7 +239,7 @@ $ docker agent setup
 
 ### `docker agent doctor`
 
-Diagnose the model and credential setup. Reports which model providers have credentials and where each credential comes from (shell environment, env file, pass, keychain, …), whether Docker Model Runner is reachable and which models are pulled, and which model the `auto` selection would pick. Secret values are never printed. Exits with a non-zero status when an issue would prevent an agent from running, which makes it usable in scripts and CI.
+Diagnose the model and credential setup. Reports which model providers have credentials and where each credential comes from (shell environment, env file, Docker Desktop, …), whether Docker Model Runner is reachable and which models are pulled, and which model the `auto` selection would pick. Secret values are never printed. Exits with a non-zero status when an issue would prevent an agent from running, which makes it usable in scripts and CI.
 
 ```bash
 $ docker agent doctor [agent-file|registry-ref] [flags]

docs/getting-started/set-up-a-model/index.md

@@ -53,11 +53,10 @@ That lasts for the current shell session. To set a key up once, use any other bu
 $ echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
 $ docker agent run --env-from-file .env
 
-# pass password manager (Linux, macOS)
-$ pass insert ANTHROPIC_API_KEY
-
-# macOS Keychain
-$ security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w
+# Docker Agent env file, read automatically on every run
+# (`docker agent setup` writes it for you with owner-only permissions)
+$ echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.config/cagent/.env
+$ chmod 600 ~/.config/cagent/.env
 ```
 
 The entry name must match the environment variable the provider expects. [Managing Secrets](../../guides/secrets/index.md) covers every source (Docker Compose secrets, credential helpers, 1Password references) and the order they are checked in.