π OpenHands: AI-Driven Development
[Docs] Add environment variables reference table (#10926)
Engel Nyst65f41647496e
diff --git a/docs/usage/configuration-options.mdx b/docs/usage/configuration-options.mdxindex 45f0885390..fc3fcdb579 100644--- a/docs/usage/configuration-options.mdx+++ b/docs/usage/configuration-options.mdx@@ -8,6 +8,11 @@ description: This page outlines all available configuration options for OpenHandIn GUI Mode, any settings applied through the Settings UI will take precedence.</Note>+<Note>+ **Looking for Environment Variables?** All configuration options can also be set using environment variables.+ See the [Environment Variables Reference](./environment-variables) for a complete list with examples.+</Note>+## Location of the `config.toml` FileWhen running OpenHands in CLI, headless, or development mode, you can use a project-specific `config.toml` file for configuration, which must be@@ -18,6 +23,11 @@ specify a different path to the `config.toml` file.The core configuration options are defined in the `[core]` section of the `config.toml` file.+Core configuration options can be set as environment variables by converting to uppercase. For example:+- `debug` β `DEBUG`+- `cache_dir` β `CACHE_DIR`+- `runtime` β `RUNTIME`+### Workspace- `workspace_base` **(Deprecated)**- Type: `str`@@ -141,6 +151,11 @@ The LLM (Large Language Model) configuration options are defined in the `[llm]`To use these with the docker command, pass in `-e LLM_<option>`. Example: `-e LLM_NUM_RETRIES`.+All LLM configuration options can be set as environment variables by prefixing with `LLM_` and converting to uppercase. For example:+- `model` β `LLM_MODEL`+- `api_key` β `LLM_API_KEY`+- `base_url` β `LLM_BASE_URL`+<Note>For development setups, you can also define custom named LLM configurations. See [Custom LLM Configurations](./llms/custom-llm-configs) for details.</Note>@@ -277,6 +292,11 @@ For development setups, you can also define custom named LLM configurations. SeeThe agent configuration options are defined in the `[agent]` and `[agent.<agent_name>]` sections of the `config.toml` file.+Agent configuration options can be set as environment variables by prefixing with `AGENT_` and converting to uppercase. For example:+- `enable_browsing` β `AGENT_ENABLE_BROWSING`+- `function_calling` β `AGENT_FUNCTION_CALLING`+- `llm_config` β `AGENT_LLM_CONFIG`+### LLM Configuration- `llm_config`- Type: `str`@@ -328,6 +348,11 @@ The sandbox configuration options are defined in the `[sandbox]` section of theTo use these with the docker command, pass in `-e SANDBOX_<option>`. Example: `-e SANDBOX_TIMEOUT`.+All sandbox configuration options can be set as environment variables by prefixing with `SANDBOX_` and converting to uppercase. For example:+- `timeout` β `SANDBOX_TIMEOUT`+- `user_id` β `SANDBOX_USER_ID`+- `base_container_image` β `SANDBOX_BASE_CONTAINER_IMAGE`+### Execution- `timeout`- Type: `int`@@ -390,6 +415,10 @@ The security configuration options are defined in the `[security]` section of thTo use these with the docker command, pass in `-e SECURITY_<option>`. Example: `-e SECURITY_CONFIRMATION_MODE`.+All security configuration options can be set as environment variables by prefixing with `SECURITY_` and converting to uppercase. For example:+- `confirmation_mode` β `SECURITY_CONFIRMATION_MODE`+- `security_analyzer` β `SECURITY_SECURITY_ANALYZER`+### Confirmation Mode- `confirmation_mode`- Type: `bool`diff --git a/docs/usage/environment-variables.mdx b/docs/usage/environment-variables.mdxnew file mode 100644index 0000000000..24d4554861--- /dev/null+++ b/docs/usage/environment-variables.mdx@@ -0,0 +1,251 @@+---+title: Environment Variables Reference+description: Complete reference of all environment variables supported by OpenHands+---++This page provides a reference of environment variables that can be used to configure OpenHands. Environment variables provide an alternative to TOML configuration files and are particularly useful for containerized deployments, CI/CD pipelines, and cloud environments.++## Environment Variable Naming Convention++OpenHands follows a consistent naming pattern for environment variables:++- **Core settings**: Direct uppercase mapping (e.g., `debug` β `DEBUG`)+- **LLM settings**: Prefixed with `LLM_` (e.g., `model` β `LLM_MODEL`)+- **Agent settings**: Prefixed with `AGENT_` (e.g., `enable_browsing` β `AGENT_ENABLE_BROWSING`)+- **Sandbox settings**: Prefixed with `SANDBOX_` (e.g., `timeout` β `SANDBOX_TIMEOUT`)+- **Security settings**: Prefixed with `SECURITY_` (e.g., `confirmation_mode` β `SECURITY_CONFIRMATION_MODE`)++## Core Configuration Variables++These variables correspond to the `[core]` section in `config.toml`:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `DEBUG` | boolean | `false` | Enable debug logging throughout the application |+| `DISABLE_COLOR` | boolean | `false` | Disable colored output in terminal |+| `CACHE_DIR` | string | `"/tmp/cache"` | Directory path for caching |+| `SAVE_TRAJECTORY_PATH` | string | `"./trajectories"` | Path to store conversation trajectories |+| `REPLAY_TRAJECTORY_PATH` | string | `""` | Path to load and replay a trajectory file |+| `FILE_STORE_PATH` | string | `"/tmp/file_store"` | File store directory path |+| `FILE_STORE` | string | `"memory"` | File store type (`memory`, `local`, etc.) |+| `FILE_UPLOADS_MAX_FILE_SIZE_MB` | integer | `0` | Maximum file upload size in MB (0 = no limit) |+| `FILE_UPLOADS_RESTRICT_FILE_TYPES` | boolean | `false` | Whether to restrict file upload types |+| `FILE_UPLOADS_ALLOWED_EXTENSIONS` | list | `[".*"]` | List of allowed file extensions for uploads |+| `MAX_BUDGET_PER_TASK` | float | `0.0` | Maximum budget per task (0.0 = no limit) |+| `MAX_ITERATIONS` | integer | `100` | Maximum number of iterations per task |+| `RUNTIME` | string | `"docker"` | Runtime environment (`docker`, `local`, `cli`, etc.) |+| `DEFAULT_AGENT` | string | `"CodeActAgent"` | Default agent class to use |+| `JWT_SECRET` | string | auto-generated | JWT secret for authentication |+| `RUN_AS_OPENHANDS` | boolean | `true` | Whether to run as the openhands user |+| `VOLUMES` | string | `""` | Volume mounts in format `host:container[:mode]` |++## LLM Configuration Variables++These variables correspond to the `[llm]` section in `config.toml`:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `LLM_MODEL` | string | `"claude-3-5-sonnet-20241022"` | LLM model to use |+| `LLM_API_KEY` | string | `""` | API key for the LLM provider |+| `LLM_BASE_URL` | string | `""` | Custom API base URL |+| `LLM_API_VERSION` | string | `""` | API version to use |+| `LLM_TEMPERATURE` | float | `0.0` | Sampling temperature |+| `LLM_TOP_P` | float | `1.0` | Top-p sampling parameter |+| `LLM_MAX_INPUT_TOKENS` | integer | `0` | Maximum input tokens (0 = no limit) |+| `LLM_MAX_OUTPUT_TOKENS` | integer | `0` | Maximum output tokens (0 = no limit) |+| `LLM_MAX_MESSAGE_CHARS` | integer | `30000` | Maximum characters that will be sent to the model in observation content |+| `LLM_TIMEOUT` | integer | `0` | API timeout in seconds (0 = no timeout) |+| `LLM_NUM_RETRIES` | integer | `8` | Number of retry attempts |+| `LLM_RETRY_MIN_WAIT` | integer | `15` | Minimum wait time between retries (seconds) |+| `LLM_RETRY_MAX_WAIT` | integer | `120` | Maximum wait time between retries (seconds) |+| `LLM_RETRY_MULTIPLIER` | float | `2.0` | Exponential backoff multiplier |+| `LLM_DROP_PARAMS` | boolean | `false` | Drop unsupported parameters without error |+| `LLM_CACHING_PROMPT` | boolean | `true` | Enable prompt caching if supported |+| `LLM_DISABLE_VISION` | boolean | `false` | Disable vision capabilities for cost reduction |+| `LLM_CUSTOM_LLM_PROVIDER` | string | `""` | Custom LLM provider name |+| `LLM_OLLAMA_BASE_URL` | string | `""` | Base URL for Ollama API |+| `LLM_INPUT_COST_PER_TOKEN` | float | `0.0` | Cost per input token |+| `LLM_OUTPUT_COST_PER_TOKEN` | float | `0.0` | Cost per output token |+| `LLM_REASONING_EFFORT` | string | `""` | Reasoning effort for o-series models (`low`, `medium`, `high`) |++### AWS Configuration+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `LLM_AWS_ACCESS_KEY_ID` | string | `""` | AWS access key ID |+| `LLM_AWS_SECRET_ACCESS_KEY` | string | `""` | AWS secret access key |+| `LLM_AWS_REGION_NAME` | string | `""` | AWS region name |++## Agent Configuration Variables++These variables correspond to the `[agent]` section in `config.toml`:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `AGENT_LLM_CONFIG` | string | `""` | Name of LLM config group to use |+| `AGENT_FUNCTION_CALLING` | boolean | `true` | Enable function calling |+| `AGENT_ENABLE_BROWSING` | boolean | `false` | Enable browsing delegate |+| `AGENT_ENABLE_LLM_EDITOR` | boolean | `false` | Enable LLM-based editor |+| `AGENT_ENABLE_JUPYTER` | boolean | `false` | Enable Jupyter integration |+| `AGENT_ENABLE_HISTORY_TRUNCATION` | boolean | `true` | Enable history truncation |+| `AGENT_ENABLE_PROMPT_EXTENSIONS` | boolean | `true` | Enable microagents (prompt extensions) |+| `AGENT_DISABLED_MICROAGENTS` | list | `[]` | List of microagents to disable |++## Sandbox Configuration Variables++These variables correspond to the `[sandbox]` section in `config.toml`:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `SANDBOX_TIMEOUT` | integer | `120` | Sandbox timeout in seconds |+| `SANDBOX_USER_ID` | integer | `1000` | User ID for sandbox processes |+| `SANDBOX_BASE_CONTAINER_IMAGE` | string | `"nikolaik/python-nodejs:python3.12-nodejs22"` | Base container image |+| `SANDBOX_USE_HOST_NETWORK` | boolean | `false` | Use host networking |+| `SANDBOX_RUNTIME_BINDING_ADDRESS` | string | `"0.0.0.0"` | Runtime binding address |+| `SANDBOX_ENABLE_AUTO_LINT` | boolean | `false` | Enable automatic linting |+| `SANDBOX_INITIALIZE_PLUGINS` | boolean | `true` | Initialize sandbox plugins |+| `SANDBOX_RUNTIME_EXTRA_DEPS` | string | `""` | Extra dependencies to install |+| `SANDBOX_RUNTIME_STARTUP_ENV_VARS` | dict | `{}` | Environment variables for runtime |+| `SANDBOX_BROWSERGYM_EVAL_ENV` | string | `""` | BrowserGym evaluation environment |+| `SANDBOX_VOLUMES` | string | `""` | Volume mounts (replaces deprecated workspace settings) |+| `SANDBOX_RUNTIME_CONTAINER_IMAGE` | string | `""` | Pre-built runtime container image |+| `SANDBOX_KEEP_RUNTIME_ALIVE` | boolean | `false` | Keep runtime alive after session ends |+| `SANDBOX_PAUSE_CLOSED_RUNTIMES` | boolean | `false` | Pause instead of stopping closed runtimes |+| `SANDBOX_CLOSE_DELAY` | integer | `300` | Delay before closing idle runtimes (seconds) |+| `SANDBOX_RM_ALL_CONTAINERS` | boolean | `false` | Remove all containers when stopping |+| `SANDBOX_ENABLE_GPU` | boolean | `false` | Enable GPU support |+| `SANDBOX_CUDA_VISIBLE_DEVICES` | string | `""` | Specify GPU devices by ID |+| `SANDBOX_VSCODE_PORT` | integer | auto | Specific port for VSCode server |++### Sandbox Environment Variables+Variables prefixed with `SANDBOX_ENV_` are passed through to the sandbox environment:++| Environment Variable | Description |+|---------------------|-------------|+| `SANDBOX_ENV_*` | Any variable with this prefix is passed to the sandbox (e.g., `SANDBOX_ENV_OPENAI_API_KEY`) |++## Security Configuration Variables++These variables correspond to the `[security]` section in `config.toml`:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `SECURITY_CONFIRMATION_MODE` | boolean | `false` | Enable confirmation mode for actions |+| `SECURITY_SECURITY_ANALYZER` | string | `"llm"` | Security analyzer to use (`llm`, `invariant`) |+| `SECURITY_ENABLE_SECURITY_ANALYZER` | boolean | `true` | Enable security analysis |++## Debug and Logging Variables++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `DEBUG` | boolean | `false` | Enable general debug logging |+| `DEBUG_LLM` | boolean | `false` | Enable LLM-specific debug logging |+| `DEBUG_RUNTIME` | boolean | `false` | Enable runtime debug logging |+| `LOG_TO_FILE` | boolean | auto | Log to file (auto-enabled when DEBUG=true) |++## Runtime-Specific Variables++### Docker Runtime+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `SANDBOX_VOLUME_OVERLAYS` | string | `""` | Volume overlay configurations |++### Remote Runtime+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `SANDBOX_API_KEY` | string | `""` | API key for remote runtime |+| `SANDBOX_REMOTE_RUNTIME_API_URL` | string | `""` | Remote runtime API URL |++### Local Runtime+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `RUNTIME_URL` | string | `""` | Runtime URL for local runtime |+| `RUNTIME_URL_PATTERN` | string | `""` | Runtime URL pattern |+| `RUNTIME_ID` | string | `""` | Runtime identifier |+| `LOCAL_RUNTIME_MODE` | string | `""` | Enable local runtime mode (`1` to enable) |++## Integration Variables++### GitHub Integration+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `GITHUB_TOKEN` | string | `""` | GitHub personal access token |++### Third-Party API Keys+| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `OPENAI_API_KEY` | string | `""` | OpenAI API key |+| `ANTHROPIC_API_KEY` | string | `""` | Anthropic API key |+| `GOOGLE_API_KEY` | string | `""` | Google API key |+| `AZURE_API_KEY` | string | `""` | Azure API key |+| `TAVILY_API_KEY` | string | `""` | Tavily search API key |++## Server Configuration Variables++These are primarily used when running OpenHands as a server:++| Environment Variable | Type | Default | Description |+|---------------------|------|---------|-------------|+| `FRONTEND_PORT` | integer | `3000` | Frontend server port |+| `BACKEND_PORT` | integer | `8000` | Backend server port |+| `FRONTEND_HOST` | string | `"localhost"` | Frontend host address |+| `BACKEND_HOST` | string | `"localhost"` | Backend host address |+| `WEB_HOST` | string | `"localhost"` | Web server host |+| `SERVE_FRONTEND` | boolean | `true` | Whether to serve frontend |++## Deprecated Variables++These variables are deprecated and should be replaced:++| Environment Variable | Replacement | Description |+|---------------------|-------------|-------------|+| `WORKSPACE_BASE` | `SANDBOX_VOLUMES` | Use volume mounting instead |+| `WORKSPACE_MOUNT_PATH` | `SANDBOX_VOLUMES` | Use volume mounting instead |+| `WORKSPACE_MOUNT_PATH_IN_SANDBOX` | `SANDBOX_VOLUMES` | Use volume mounting instead |+| `WORKSPACE_MOUNT_REWRITE` | `SANDBOX_VOLUMES` | Use volume mounting instead |++## Usage Examples++### Basic Setup with OpenAI+```bash+export LLM_MODEL="gpt-4o"+export LLM_API_KEY="your-openai-api-key"+export DEBUG=true+```++### Docker Deployment with Custom Volumes+```bash+export RUNTIME="docker"+export SANDBOX_VOLUMES="/host/workspace:/workspace:rw,/host/data:/data:ro"+export SANDBOX_TIMEOUT=300+```++### Remote Runtime Configuration+```bash+export RUNTIME="remote"+export SANDBOX_API_KEY="your-remote-api-key"+export SANDBOX_REMOTE_RUNTIME_API_URL="https://your-runtime-api.com"+```++### Security-Enhanced Setup+```bash+export SECURITY_CONFIRMATION_MODE=true+export SECURITY_SECURITY_ANALYZER="llm"+export DEBUG_RUNTIME=true+```++## Notes++1. **Boolean Values**: Environment variables expecting boolean values accept `true`/`false`, `1`/`0`, or `yes`/`no` (case-insensitive).++2. **List Values**: Lists should be provided as Python literal strings, e.g., `AGENT_DISABLED_MICROAGENTS='["microagent1", "microagent2"]'`.++3. **Dictionary Values**: Dictionaries should be provided as Python literal strings, e.g., `SANDBOX_RUNTIME_STARTUP_ENV_VARS='{"KEY": "value"}'`.++4. **Precedence**: Environment variables take precedence over TOML configuration files.++5. **Docker Usage**: When using Docker, pass environment variables with the `-e` flag:+ ```bash+ docker run -e LLM_API_KEY="your-key" -e DEBUG=true openhands/openhands+ ```++6. **Validation**: Invalid environment variable values will be logged as errors and fall back to defaults.\ No newline at end of file