block · dianed-square · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026
@@ -371,7 +371,7 @@ Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats. T
        - **Display Name**: A friendly name for the provider
        - **API URL**: The base URL of the API endpoint
        - **Authentication**:
-         - **API Key**: The API key, which is accessed using a custom environment variable and stored in the keychain (or `secrets.yaml` if the keyring is disabled)
+         - **API Key**: The API key, which is accessed using a custom environment variable and stored in the keychain (or `secrets.yaml` if the keyring is disabled or cannot be accessed)
             - For providers that don't require authorization (e.g., local models like Ollama, vLLM, LM Studio, or internal APIs), uncheck the **"This provider requires an API key"** checkbox
        - **Available Models**: Comma-separated list of available model names
        - **Streaming Support**: Whether the API supports streaming responses (click to toggle)
@@ -430,7 +430,7 @@ Custom providers must use OpenAI, Anthropic, or Ollama compatible API formats. T
        - **Name**: A friendly name for the provider
        - **API URL**: The base URL of the API endpoint
        - **Authentication Required**: Answer "Yes" if your provider needs an API key, or "No" if authentication is not required
-         - If Yes: You'll be prompted to enter your **API Key** (stored securely in the keychain or `secrets.yaml`)
+         - If Yes: You'll be prompted to enter your **API Key** (stored securely in the keychain, or in `secrets.yaml` if the keyring is disabled or cannot be accessed)
          - If No: The API key prompt is skipped
        - **Available Models**: Comma-separated list of available model names
        - **Streaming Support**: Whether the API supports streaming responses

@@ -17,7 +17,7 @@ The configuration files allow you to set default behaviors, configure language m
 
 - **config.yaml** - Provider, model, extensions, and general settings
 - **permission.yaml** - Tool permission levels configured via `goose configure`
-- **secrets.yaml** - API keys and secrets (only when keyring is disabled)
+- **secrets.yaml** - API keys and secrets (when goose is using [file-based secret storage](#security-considerations))
 - **permissions/tool_permissions.json** - Runtime permission decisions (auto-managed)
 - **prompts/** - Customized [prompt templates](/docs/guides/prompt-templates)
 
@@ -177,8 +177,14 @@ Settings are applied in the following order of precedence:
 ## Security Considerations
 
 - Avoid storing sensitive information (API keys, tokens) in the config file
-- Use the system keyring for storing secrets
-- If keyring is disabled, secrets are stored in a separate `secrets.yaml` file
+- Use the system keyring (keychain on macOS) for storing secrets. When available, this is the recommended option.
+- If goose is using file-based secret storage, secrets are stored in a separate `secrets.yaml` file (in plain text). This can happen when:
+
+  - Your environment does not provide a desktop keyring service (for example: headless servers, CI/CD, containers)
+  - You disable the keyring explicitly (via [GOOSE_DISABLE_KEYRING](/docs/guides/environment-variables#security-and-privacy))
+  - goose cannot access the keyring and falls back to file-based secret storage
+
+  For troubleshooting keyring failures and automatic fallback behavior, see [Known Issues](/docs/troubleshooting/known-issues#keyring-cannot-be-accessed-automatic-fallback).
 
 ## Updating Configuration
 

@@ -402,7 +402,7 @@ export GOOSE_TELEMETRY_ENABLED=true   # Enable telemetry
 ```
 
 :::tip
-When the keyring is disabled, secrets are stored here:
+When the keyring is disabled (or cannot be accessed and goose [falls back to file-based storage](/docs/troubleshooting/known-issues#keyring-cannot-be-accessed-automatic-fallback)), secrets are stored here:
 
 * macOS/Linux: `~/.config/goose/secrets.yaml`
 * Windows: `%APPDATA%\Block\goose\config\secrets.yaml`

@@ -133,21 +133,23 @@ To resolve:
 
 #### Container and Keyring Issues
 
-If you're running goose in Docker containers or Linux environments without keyring support, authentication may fail with keyring errors like:
-```
-Failed to save token: Failed to access keyring: Platform secure storage failure: DBus error: Using X11 for dbus-daemon autolaunch was disabled at compile time
-```
+goose tries to use the system keyring (typically via Secret Service over DBus) to securely store your GitHub Copilot token. In containerized or headless environments, DBus and/or a desktop keyring service may not be available (and some setups fail with X11-based DBus autolaunch errors), so keyring access can fail.
 
-goose tries to use the system keyring (which requires DBus and X11) to securely store your GitHub token, but these aren't available in containerized or headless environments.
+If you're running goose in Docker containers or Linux environments without keyring support, goose may automatically fall back to [file-based secret storage](#keyring-cannot-be-accessed-automatic-fallback).
 
-To resolve:
+If you still receive authentication/keyring errors like the following, goose was not able to fall back automatically. This can happen if goose doesn’t recognize the keyring failure as an access issue, or if the error is unrelated to keyring access.
+```
+Failed to save token: Failed to access keyring: <error message>
+```
 
-Use the `GOOSE_DISABLE_KEYRING` environment variable to tell goose to store secrets in files instead. This example sets the variable only while executing the `goose configure` command:
+To resolve this (or to proactively force file-based secret storage), set `GOOSE_DISABLE_KEYRING` to any value. This example sets it only while running `goose configure`:
 
 ```bash
 GOOSE_DISABLE_KEYRING=1 goose configure
 ```
 
+If you prefer not to store secrets in `secrets.yaml`, set the token via environment variables instead.
+
 See [Keychain/Keyring Errors](#keychainkeyring-errors) for more details on keyring alternatives.
 
 ---
@@ -161,7 +163,7 @@ This warning helps protect against inadvertently executing potentially harmful r
 ---
 ### Uninstall goose or Remove Cached Data
 
-You may need to uninstall goose or clear existing data before re-installing. goose stores data in different locations depending on your operating system. Secrets, such as API keys, are stored exclusively in the system keychain/keyring.
+You may need to uninstall goose or clear existing data before re-installing. goose stores data in different locations depending on your operating system. Secrets, such as API keys, are stored in the system keychain/keyring by default (or in `secrets.yaml` when file-based secret storage is in use).
 
 #### macOS
 
@@ -231,52 +233,81 @@ rmdir /s /q "%LOCALAPPDATA%\Block\goose"
 
 ### Keychain/Keyring Errors
 
-goose tries to use the system keyring to store secrets. In environments where there is no keyring support, you may
-see an error like:
+goose tries to use the system keyring (keychain on macOS) to store secrets by default. In environments where the keyring cannot be accessed (or there is no keyring support), you may see an error like:
 
 ```bash
 Error Failed to access secure storage (keyring): Platform secure storage failure: DBus error: The name org.freedesktop.secrets was not provided by any .service files
 Please check your system keychain and run 'goose configure' again.
 If your system is unable to use the keyring, please try setting secret key(s) via environment variables.
 ```
 
-In this case, you will need to set your provider specific environment variable(s), which can be found at [Supported LLM Providers][configure-llm-provider].
+In some cases, goose may automatically fall back to file-based secret storage. See [Keyring Cannot Be Accessed (Automatic Fallback)](#keyring-cannot-be-accessed-automatic-fallback).
 
-You can set them either by doing:
-* `export GOOGLE_API_KEY=$YOUR_KEY_HERE` - for the duration of your session
-* in your `~/.bashrc` or `~/.zshrc` - (or equivalents) so it persists on new shell each new session
+If you still receive keyring errors, use one of the following options:
 
-Then select the `No` option when prompted to save the value to your keyring.
+- **Set provider-specific environment variable(s)**, which can be found at [Supported LLM Providers][configure-llm-provider].
+  - For the duration of your session: `export GOOGLE_API_KEY=$YOUR_KEY_HERE`
+  - To persist across new shells: add it to your `~/.bashrc` or `~/.zshrc` (or equivalents)
 
-```bash
-$ goose configure
-
-Welcome to goose! Let's get you set up with a provider.
-  you can rerun this command later to update your configuration
-
-┌   goose-configure
-│
-◇  Which model provider should we use?
-│  Google Gemini
-│
-◇  GOOGLE_API_KEY is set via environment variable
-│
-◇  Would you like to save this value to your keyring?
-│  No
-│
-◇  Enter a model from that provider:
-│  gemini-2.0-flash-exp
-```
+    Then select the `No` option when prompted to save the value to your keyring.
+
+  ```bash
+  $ goose configure
+
+  Welcome to goose! Let's get you set up with a provider.
+    you can rerun this command later to update your configuration
+
+  ┌   goose-configure
+  │
+  ◇  Which model provider should we use?
+  │  Google Gemini
+  │
+  ◇  GOOGLE_API_KEY is set via environment variable
+  │
+  ◇  Would you like to save this value to your keyring?
+  │  No
+  │
+  ◇  Enter a model from that provider:
+  │  gemini-2.0-flash-exp
+  ```
+
+- **If you need to disable the keyring**, set `GOOSE_DISABLE_KEYRING` to any value to force file-based secret storage. The actual value doesn't matter, only whether the variable is set.
+
+  This example sets it only while running `goose configure`:
 
-You may also use the `GOOSE_DISABLE_KEYRING` environment variable, which disables the system keyring for secret storage. Set to any value (e.g., "1", "true", "yes"), to disable. The actual value doesn't matter, only whether the variable is set.
+  ```bash
+  GOOSE_DISABLE_KEYRING=1 goose configure
+  ```
+
+When the keyring is disabled (or cannot be accessed and goose falls back to file-based secret storage), secrets are stored here:
 
-When the keyring is disabled, secrets are stored here:
+- macOS/Linux: `~/.config/goose/secrets.yaml`
+- Windows: `%APPDATA%\Block\goose\config\secrets.yaml`
 
-* macOS/Linux: `~/.config/goose/secrets.yaml`
-* Windows: `%APPDATA%\Block\goose\config\secrets.yaml`
+See [Configuration Files](/docs/guides/config-files) for details.
 
 ---
 
+### Keyring Cannot Be Accessed (Automatic Fallback)
+
+goose uses the system keyring (keychain on macOS) to store secrets by default. If the keyring cannot be accessed, goose may fall back to file-based secret storage.
+
+In this case, you may see a warning like the following in logs:
+
+```text
+Keyring unavailable. Using file storage for secrets.
+```
+
+Automatic fallback only applies to the current goose process. When you start a new session, goose will try to use the keyring again.
+
+If you need to force file-based secret storage (for example, in containers or headless environments), set `GOOSE_DISABLE_KEYRING` to any value:
+
+```bash
+GOOSE_DISABLE_KEYRING=1 goose configure
+```
+
+See [Configuration Files](/docs/guides/config-files) for `secrets.yaml` details.
+
 ### Package Runners
 
 Many of the external extensions require a package runner. For example, if you run into an error like this one: