> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-jp-canvas-link-ohe-quickstart.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables Reference

> 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 skills (formerly known as microagents) (prompt extensions) |
| `AGENT_DISABLED_MICROAGENTS`      | list    | `[]`    | List of skills 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)                      |
| `AGENT_SERVER_IMAGE_REPOSITORY`    | string  | `""`                                           | Runtime container image repository (e.g., `ghcr.io/openhands/agent-server`) |
| `AGENT_SERVER_IMAGE_TAG`           | string  | `""`                                           | Runtime container image tag (e.g., `1.26.0-python`)                         |
| `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 |

### Docker Conversation Runtime (Canvas)

When running Agent Canvas locally via the `dev-safe.mjs` launcher, Canvas can forward conversation-runtime settings to its bundled Agent Server. This enables `OH_CONVERSATION_RUNTIME=docker`, which runs each conversation in an isolated Docker container instead of the default local process runtime.

Canvas forwards these settings only when the operator explicitly sets them. Unset values remain absent so Agent Server defaults stay authoritative.

| Environment Variable                        | Type   | Default | Description                                                                           |
| ------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------- |
| `OH_CONVERSATION_RUNTIME`                   | string | unset   | Conversation runtime type. Set to `docker` to run conversations in Docker containers. |
| `OH_CONVERSATION_IMAGE`                     | string | unset   | Docker image to use for conversation containers.                                      |
| `OH_CONVERSATION_CONTAINER_MEMORY`          | string | unset   | Memory limit for conversation containers (e.g., `2g`).                                |
| `OH_CONVERSATION_CONTAINER_CPUS`            | string | unset   | CPU limit for conversation containers.                                                |
| `OH_CONVERSATION_CONTAINER_PIDS_LIMIT`      | string | unset   | PID limit for conversation containers.                                                |
| `OH_CONVERSATION_CONTAINER_STARTUP_TIMEOUT` | string | unset   | Startup timeout for conversation containers (seconds).                                |

These variables are specific to Canvas's `dev-safe.mjs` launcher and are forwarded to the bundled Agent Server process. Docker provisioning and setting interpretation are handled by Agent Server.

### 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

### Git Provider Access

| Environment Variable        | Type    | Default | Description                                                                                                                                                                  |
| --------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW_INSECURE_GIT_ACCESS` | boolean | `false` | Allow OpenHands to connect to git providers over plain HTTP. Set this only for trusted local or internal git providers (such as Gitea/Forgejo) where HTTPS is not available. |

<Warning>
  `ALLOW_INSECURE_GIT_ACCESS=true` permits insecure HTTP connections to git providers. Only enable it for trusted local or internal networks that you control. Do not use it for public or untrusted git providers.
</Warning>

When running OpenHands with Docker, set this on the OpenHands server container:

```bash theme={null}
docker run -e ALLOW_INSECURE_GIT_ACCESS=true openhands/openhands
```

### 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 theme={null}
export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-openai-api-key"
export DEBUG=true
```

### Docker Deployment with Custom Volumes

```bash theme={null}
export RUNTIME="docker"
export SANDBOX_VOLUMES="/host/workspace:/workspace:rw,/host/data:/data:ro"
export SANDBOX_TIMEOUT=300
```

### Remote Runtime Configuration

```bash theme={null}
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 theme={null}
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='["skill1", "skill2"]'`.

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 theme={null}
   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.