> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-feature-use-case-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Options

> This page outlines all available configuration options for OpenHands, allowing you to customize its behavior and integrate it with other services.

<Note>
  This page documents **legacy OpenHands V0** behavior. For the current V1
  sandbox model, see [Sandboxes (V1)](/openhands/usage/sandboxes/overview).
</Note>

<Note>
  These settings are only available in [Local GUI](/openhands/usage/run-openhands/local-setup). OpenHands Cloud uses a web-based settings interface.
</Note>

<Note>
  In 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](/openhands/usage/environment-variables) for a complete list with examples.
</Note>

## Location of the `config.toml` File

When running OpenHands in CLI, headless, or development mode, you can use a project-specific `config.toml` file for configuration, which must be
located in the same directory from which the command is run. Alternatively, you may use the `--config-file` option to
specify a different path to the `config.toml` file.

## Core Configuration

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`
  * Default: `"./workspace"`
  * Description: Base path for the workspace. **Deprecated: Use `SANDBOX_VOLUMES` instead.**

* `cache_dir`
  * Type: `str`
  * Default: `"/tmp/cache"`
  * Description: Cache directory path

### Debugging and Logging

* `debug`
  * Type: `bool`
  * Default: `false`
  * Description: Enable debugging

* `disable_color`
  * Type: `bool`
  * Default: `false`
  * Description: Disable color in terminal output

### Trajectories

* `save_trajectory_path`
  * Type: `str`
  * Default: `"./trajectories"`
  * Description: Path to store trajectories (can be a folder or a file). If it's a folder, the trajectories will be saved in a file named with the session id name and .json extension, in that folder.

* `replay_trajectory_path`
  * Type: `str`
  * Default: `""`
  * Description: Path to load a trajectory and replay. If given, must be a path to the trajectory file in JSON format. The actions in the trajectory file would be replayed first before any user instruction is executed.

### File Store

* `file_store_path`
  * Type: `str`
  * Default: `"/tmp/file_store"`
  * Description: File store path

* `file_store`
  * Type: `str`
  * Default: `"memory"`
  * Description: File store type

* `file_uploads_allowed_extensions`
  * Type: `list of str`
  * Default: `[".*"]`
  * Description: List of allowed file extensions for uploads

* `file_uploads_max_file_size_mb`
  * Type: `int`
  * Default: `0`
  * Description: Maximum file size for uploads, in megabytes

* `file_uploads_restrict_file_types`
  * Type: `bool`
  * Default: `false`
  * Description: Restrict file types for file uploads

* `file_uploads_allowed_extensions`
  * Type: `list of str`
  * Default: `[".*"]`
  * Description: List of allowed file extensions for uploads

### Task Management

* `max_budget_per_task`
  * Type: `float`
  * Default: `0.0`
  * Description: Maximum budget per task (0.0 means no limit)

* `max_iterations`
  * Type: `int`
  * Default: `100`
  * Description: Maximum number of iterations

### Sandbox Configuration

* `volumes`
  * Type: `str`
  * Default: `None`
  * Description: Volume mounts in the format 'host\_path:container\_path\[:mode]', e.g. '/my/host/dir:/workspace:rw'. Multiple mounts can be specified using commas, e.g. '/path1:/workspace/path1,/path2:/workspace/path2:ro'

* `workspace_mount_path_in_sandbox` **(Deprecated)**
  * Type: `str`
  * Default: `"/workspace"`
  * Description: Path to mount the workspace in the sandbox. **Deprecated: Use `SANDBOX_VOLUMES` instead.**

* `workspace_mount_path` **(Deprecated)**
  * Type: `str`
  * Default: `""`
  * Description: Path to mount the workspace. **Deprecated: Use `SANDBOX_VOLUMES` instead.**

* `workspace_mount_rewrite` **(Deprecated)**
  * Type: `str`
  * Default: `""`
  * Description: Path to rewrite the workspace mount path to. You can usually ignore this, it refers to special cases of running inside another container. **Deprecated: Use `SANDBOX_VOLUMES` instead.**

### Miscellaneous

* `run_as_openhands`
  * Type: `bool`
  * Default: `true`
  * Description: Run as OpenHands

* `runtime`
  * Type: `str`
  * Default: `"docker"`
  * Description: Runtime environment

* `default_agent`
  * Type: `str`
  * Default: `"CodeActAgent"`
  * Description: Name of the default agent

* `jwt_secret`
  * Type: `str`
  * Default: `uuid.uuid4().hex`
  * Description: JWT secret for authentication. Please set it to your own value.

## LLM Configuration

The LLM (Large Language Model) configuration options are defined in the `[llm]` section of the `config.toml` file.

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](/openhands/usage/llms/custom-llm-configs) for details.
</Note>

**AWS Credentials**

* `aws_access_key_id`
  * Type: `str`
  * Default: `""`
  * Description: AWS access key ID

* `aws_region_name`
  * Type: `str`
  * Default: `""`
  * Description: AWS region name

* `aws_secret_access_key`
  * Type: `str`
  * Default: `""`
  * Description: AWS secret access key

### API Configuration

* `api_key`
  * Type: `str`
  * Default: `None`
  * Description: API key to use

* `base_url`
  * Type: `str`
  * Default: `""`
  * Description: API base URL

* `api_version`
  * Type: `str`
  * Default: `""`
  * Description: API version

* `input_cost_per_token`
  * Type: `float`
  * Default: `0.0`
  * Description: Cost per input token

* `output_cost_per_token`
  * Type: `float`
  * Default: `0.0`
  * Description: Cost per output token

### Custom LLM Provider

* `custom_llm_provider`
  * Type: `str`
  * Default: `""`
  * Description: Custom LLM provider

### Message Handling

* `max_message_chars`
  * Type: `int`
  * Default: `30000`
  * Description: The approximate maximum number of characters in the content of an event included in the prompt to the LLM. Larger observations are truncated.

* `max_input_tokens`
  * Type: `int`
  * Default: `0`
  * Description: Maximum number of input tokens

* `max_output_tokens`
  * Type: `int`
  * Default: `0`
  * Description: Maximum number of output tokens

### Model Selection

* `model`
  * Type: `str`
  * Default: `"claude-3-5-sonnet-20241022"`
  * Description: Model to use

### Retrying

* `num_retries`
  * Type: `int`
  * Default: `8`
  * Description: Number of retries to attempt

* `retry_max_wait`
  * Type: `int`
  * Default: `120`
  * Description: Maximum wait time (in seconds) between retry attempts

* `retry_min_wait`
  * Type: `int`
  * Default: `15`
  * Description: Minimum wait time (in seconds) between retry attempts

* `retry_multiplier`
  * Type: `float`
  * Default: `2.0`
  * Description: Multiplier for exponential backoff calculation

### Advanced Options

* `drop_params`
  * Type: `bool`
  * Default: `false`
  * Description: Drop any unmapped (unsupported) params without causing an exception

* `caching_prompt`
  * Type: `bool`
  * Default: `true`
  * Description: Using the prompt caching feature if provided by the LLM and supported

* `ollama_base_url`
  * Type: `str`
  * Default: `""`
  * Description: Base URL for the OLLAMA API

* `temperature`
  * Type: `float`
  * Default: `0.0`
  * Description: Temperature for the API

* `timeout`
  * Type: `int`
  * Default: `0`
  * Description: Timeout for the API

* `top_p`
  * Type: `float`
  * Default: `1.0`
  * Description: Top p for the API

* `disable_vision`
  * Type: `bool`
  * Default: `None`
  * Description: If model is vision capable, this option allows to disable image processing (useful for cost reduction)

## Agent Configuration

The 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`
  * Default: `'your-llm-config-group'`
  * Description: The name of the LLM config to use

### ActionSpace Configuration

* `function_calling`
  * Type: `bool`
  * Default: `true`
  * Description: Whether function calling is enabled

* `enable_browsing`
  * Type: `bool`
  * Default: `false`
  * Description: Whether browsing delegate is enabled in the action space (only works with function calling)

* `enable_llm_editor`
  * Type: `bool`
  * Default: `false`
  * Description: Whether LLM editor is enabled in the action space (only works with function calling)

* `enable_jupyter`
  * Type: `bool`
  * Default: `false`
  * Description: Whether Jupyter is enabled in the action space

* `enable_history_truncation`
  * Type: `bool`
  * Default: `true`
  * Description: Whether history should be truncated to continue the session when hitting LLM context length limit

### Skills (formerly Microagents) Usage

* `enable_prompt_extensions`
  * Type: `bool`
  * Default: `true`
  * Description: Whether to use skills at all

* `disabled_microagents`
  * Type: `list of str`
  * Default: `None`
  * Description: A list of skills to disable

## Sandbox Configuration

The sandbox configuration options are defined in the `[sandbox]` section of the `config.toml` file.

To 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`
  * Default: `120`
  * Description: Sandbox timeout in seconds

* `user_id`
  * Type: `int`
  * Default: `1000`
  * Description: Sandbox user ID

### Container Image

* `base_container_image`
  * Type: `str`
  * Default: `"nikolaik/python-nodejs:python3.12-nodejs22"`
  * Description: Container image to use for the sandbox

### Networking

* `use_host_network`
  * Type: `bool`
  * Default: `false`
  * Description: Use host network

* `runtime_binding_address`
  * Type: `str`
  * Default: `0.0.0.0`
  * Description: The binding address for the runtime ports.  It specifies which network interface on the host machine Docker should bind the runtime ports to.

### Linting and Plugins

* `enable_auto_lint`
  * Type: `bool`
  * Default: `false`
  * Description: Enable auto linting after editing

* `initialize_plugins`
  * Type: `bool`
  * Default: `true`
  * Description: Whether to initialize plugins

### Dependencies and Environment

* `runtime_extra_deps`
  * Type: `str`
  * Default: `""`
  * Description: Extra dependencies to install in the runtime image

* `runtime_startup_env_vars`
  * Type: `dict`
  * Default: `{}`
  * Description: Environment variables to set at the launch of the runtime

### Evaluation

* `browsergym_eval_env`
  * Type: `str`
  * Default: `""`
  * Description: BrowserGym environment to use for evaluation

## Security Configuration

The security configuration options are defined in the `[security]` section of the `config.toml` file.

To 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`
  * Default: `false`
  * Description: Enable confirmation mode

### Security Analyzer

* `security_analyzer`
  * Type: `str`
  * Default: `""`
  * Description: The security analyzer to use

***

> **Note**: Adjust configurations carefully, especially for memory, security, and network-related settings to ensure optimal performance and security.
> Please note that the configuration options may be subject to change in future versions of OpenHands. It's recommended to refer to the official documentation for the most up-to-date information.