From 2dc2301fa426dd3bfa077ee39d9eaaf5aeae6133 Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Tue, 29 Apr 2025 11:32:41 -0400 Subject: [PATCH] docs: list of environment variables (#2369) --- .../docs/guides/environment-variables.md | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 documentation/docs/guides/environment-variables.md diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md new file mode 100644 index 0000000000..43d08fa8bc --- /dev/null +++ b/documentation/docs/guides/environment-variables.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 20 +title: Environment Variables +sidebar_label: Environment Variables +--- + +Goose supports various environment variables that allow you to customize its behavior. This guide provides a comprehensive list of available environment variables grouped by their functionality. + +## Model Configuration + +These variables control the [language models](/docs/getting-started/providers) and their behavior. +### Basic Provider Configuration + +These are the minimum required variables to get started with Goose. + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_PROVIDER` | Specifies the LLM provider to use | [See available providers](/docs/getting-started/providers#available-providers) | None (must be [configured](/docs/getting-started/providers#configure-provider)) | +| `GOOSE_MODEL` | Specifies which model to use from the provider | Model name (e.g., "gpt-4", "claude-3.5-sonnet") | None (must be configured) | +| `GOOSE_TEMPERATURE` | Sets the [temperature](https://medium.com/@kelseyywang/a-comprehensive-guide-to-llm-temperature-%EF%B8%8F-363a40bbc91f) for model responses | Float between 0.0 and 1.0 | Model-specific default | + +**Examples** + +```bash +# Basic model configuration +export GOOSE_PROVIDER="anthropic" +export GOOSE_MODEL="claude-3.5-sonnet" +export GOOSE_TEMPERATURE=0.7 +``` +### Advanced Provider Configuration + +These variables are needed when using custom endpoints, enterprise deployments, or specific provider implementations. + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_PROVIDER__TYPE` | The specific type/implementation of the provider | [See available providers](/docs/getting-started/providers#available-providers) | Derived from GOOSE_PROVIDER | +| `GOOSE_PROVIDER__HOST` | Custom API endpoint for the provider | URL (e.g., "https://api.openai.com") | Provider-specific default | +| `GOOSE_PROVIDER__API_KEY` | Authentication key for the provider | API key string | None | + +**Examples** + +```bash +# Advanced provider configuration +export GOOSE_PROVIDER__TYPE="anthropic" +export GOOSE_PROVIDER__HOST="https://api.anthropic.com" +export GOOSE_PROVIDER__API_KEY="your-api-key-here" +## Planning Mode Configuration + +These variables control Goose's [planning functionality](/docs/guides/creating-plans). + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_PLANNER_PROVIDER` | Specifies which provider to use for planning mode | [See available providers](/docs/getting-started/providers#available-providers) | Falls back to GOOSE_PROVIDER | +| `GOOSE_PLANNER_MODEL` | Specifies which model to use for planning mode | Model name (e.g., "gpt-4", "claude-3.5-sonnet")| Falls back to GOOSE_MODEL | + +**Examples** + +```bash +# Planning mode with different model +export GOOSE_PLANNER_PROVIDER="openai" +export GOOSE_PLANNER_MODEL="gpt-4" +``` + +## Tool Configuration + +These variables control how Goose handles [tool permissions](/docs/guides/tool-permissions) and their execution. + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_MODE` | Controls how Goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "smart_approve" | +| `GOOSE_TOOLSHIM` | Enables/disables tool call interpretation | "1", "true" (case insensitive) to enable | false | +| `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Specifies the model for [tool call interpretation](/docs/guides/experimental-features/#ollama-tool-shim) | Model name (e.g. llama3.2, qwen2.5) | System default | +| `GOOSE_CLI_MIN_PRIORITY` | Controls verbosity of [tool output](/docs/guides/adjust-tool-output) | Float between 0.0 and 1.0 | 0.0 | + +**Examples** + +```bash +# Enable tool interpretation +export GOOSE_TOOLSHIM=true +export GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2 +export GOOSE_MODE="auto" +export GOOSE_CLI_MIN_PRIORITY=0.2 # Show only medium and high importance output + +## Security Configuration + +These variables control security related features. + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_ALLOWLIST` | Controls which extensions can be loaded | URL for [allowed extensions](/docs/guides/allowlist) list | Unset | +| `GOOSE_DISABLE_KEYRING` | 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. | Unset (keyring enabled) | + +:::tip +When the keyring is disabled, secrets are stored here: + +* macOS/Linux: `~/.config/goose/secrets.yaml` +* Windows: `%APPDATA%\Block\goose\config\secrets.yaml` +::: + + +## Langfuse Integration + +These variables configure the [Langfuse integration for observability](/docs/tutorials/langfuse). + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `LANGFUSE_PUBLIC_KEY` | Public key for Langfuse integration | String | None | +| `LANGFUSE_SECRET_KEY` | Secret key for Langfuse integration | String | None | +| `LANGFUSE_URL` | Custom URL for Langfuse service | URL String | Default Langfuse URL | +| `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` | Alternative public key for Langfuse | String | None | +| `LANGFUSE_INIT_PROJECT_SECRET_KEY` | Alternative secret key for Langfuse | String | None | + + +## Notes + +- Environment variables take precedence over configuration files. +- For security-sensitive variables (like API keys), consider using the system keyring instead of environment variables. +- Some variables may require restarting Goose to take effect. +- When using the planning mode, if planner-specific variables are not set, Goose will fall back to the main model configuration. +