OpenHands Config: Mastering Config.toml For HerringtonDarkholme

by Natalie Brooks 64 views

Hey guys! Ever felt like you're just scratching the surface with OpenHands? You're not alone! To really unleash its power, you need to dive into the config.toml file. This is where the magic happens, where you can tweak settings to perfectly match your needs. This comprehensive guide will walk you through every nook and cranny of the OpenHands configuration, helping you optimize it for your specific use case, whether it's for the HerringtonDarkholme project or a mega-repo.

Understanding OpenHands Configuration

This guide delves into the OpenHands configuration options, offering a comprehensive overview of how to tailor its behavior and integrate it seamlessly with various services. This guide will focus on the config.toml file, the heart of OpenHands customization. You'll find this file in the ~/.openhands/ directory, but settings can also be managed through a config.toml file in your current project directory. Let's explore how to master this configuration and unlock the full potential of OpenHands.

Why config.toml Matters: The config.toml file is where you fine-tune OpenHands for optimal performance and security. It allows you to set everything from API keys and file storage paths to sandbox timeouts and agent behavior. Think of it as the control panel for your OpenHands experience. Understanding these configurations is crucial for any serious OpenHands user.

GUI vs. CLI Configuration: Keep in mind that if you're using the GUI mode, settings applied there will override those in the config.toml file. This is super handy for quick adjustments, but for persistent configurations, config.toml is your best friend. This ensures that your settings are consistent across different sessions and environments.

Locating Your config.toml File

When you're running OpenHands in CLI, headless mode, or even during development, you've got a couple of options for specifying your config.toml file. The most straightforward way is to keep a project-specific config.toml in the same directory from where you're running your commands. OpenHands will automatically pick it up from there. Alternatively, if you want to use a config.toml file located elsewhere, you can use the --config-file option followed by the path to your file. For example:

openhands --config-file /path/to/your/config.toml

This flexibility allows you to manage configurations effectively, whether you're working on multiple projects with different settings or prefer a centralized configuration file. Knowing where to place and how to specify your config.toml is the first step towards mastering OpenHands configuration.

Core Configuration Options ([core])

The [core] section of your config.toml file is where you'll find the fundamental settings that govern OpenHands' overall behavior. Let's break down some of the key options:

Workspace and Caching

  • workspace_base (Deprecated): This setting used to define the base path for your workspace. However, it's now deprecated in favor of SANDBOX_VOLUMES. We'll dive into SANDBOX_VOLUMES later, but for now, just know that this option is on its way out.
  • cache_dir: This is where OpenHands stores cached data. By default, it's set to "/tmp/cache". You might want to change this to a more persistent location if you're dealing with large datasets or want to preserve your cache across sessions. A well-configured cache directory can significantly speed up your OpenHands workflows.

Debugging and Logging

  • debug: This boolean setting enables debugging mode. When set to true, OpenHands will output more verbose logs, which can be invaluable for troubleshooting. If you're encountering issues, enabling debugging is a great first step.
  • disable_color: If you prefer plain text output without any color codes in your terminal, set this to true. By default, it's false, which means you'll see color-coded logs and output. Disabling color can be useful in certain environments or if you have visual impairments.

Trajectories

  • save_trajectory_path: This setting determines where OpenHands saves trajectories, which are records of the actions taken during a session. You can specify either a folder or a file path. If you specify a folder, OpenHands will save each trajectory in a separate JSON file named after the session ID. Saving trajectories is incredibly useful for debugging and replaying past sessions. You might want to adjust this path to a dedicated directory for your trajectory data.
  • replay_trajectory_path: This allows you to load and replay a previously saved trajectory. Simply provide the path to the JSON file, and OpenHands will execute the actions in that trajectory before processing any new instructions. This is a powerful feature for reproducing specific scenarios or debugging complex workflows. Understanding how to use trajectories is a game-changer for OpenHands development.

File Store

  • file_store_path: This sets the base path for the file store, which is where OpenHands manages files. The default is "/tmp/file_store", but you'll likely want to change this to a more permanent location. A well-defined file store path ensures that your files are stored safely and accessibly.
  • file_store: This option specifies the type of file store to use. The default is "memory", which means files are stored in memory and will be lost when the OpenHands process terminates. For persistent storage, you'll need to explore other options like disk-based storage. Choosing the right file store is crucial for data persistence.
  • file_uploads_allowed_extensions: This is a list of file extensions that are allowed for uploads. The default is [".*"], which means all file types are allowed. You can restrict uploads to specific file types by listing their extensions here, for instance, [".txt", ".pdf", ".jpg"]. Restricting file extensions is an important security measure.
  • file_uploads_max_file_size_mb: This sets the maximum file size for uploads, in megabytes. A value of 0 means there's no limit. Setting a maximum file size helps prevent resource exhaustion and potential security vulnerabilities.
  • file_uploads_restrict_file_types: This boolean option, if set to true, enforces the allowed file extensions specified in file_uploads_allowed_extensions. If set to false, it doesn't restrict file types. Ensuring proper file type restriction is crucial for maintaining system integrity.

Task Management

  • max_budget_per_task: This sets the maximum budget (in some unit, likely tokens or cost) that a task can consume. A value of 0.0 means there's no limit. Setting a budget per task can help you control costs and prevent runaway processes.
  • max_iterations: This specifies the maximum number of iterations a task can run for. The default is 100. Limiting iterations is another way to prevent tasks from running indefinitely.

Sandbox Configuration

  • volumes: This is where you define volume mounts for the sandbox, using the format 'host_path:container_path[:mode]'. For example, '/my/host/dir:/workspace:rw' mounts the /my/host/dir directory on your host machine to the /workspace directory inside the sandbox, with read-write access (rw). You can specify multiple mounts using commas, like this: '/path1:/workspace/path1,/path2:/workspace/path2:ro'. This is a powerful way to share files and directories between your host machine and the sandbox. Mastering volume mounts is essential for many OpenHands workflows.
  • workspace_mount_path_in_sandbox (Deprecated): This option used to define the path to mount the workspace in the sandbox. It's now deprecated in favor of SANDBOX_VOLUMES.
  • workspace_mount_path (Deprecated): This also used to define the path to mount the workspace and is now deprecated.
  • workspace_mount_rewrite (Deprecated): This was used to rewrite the workspace mount path, but it's also deprecated. You can safely ignore this unless you're dealing with very specific container setups.

Miscellaneous

  • run_as_openhands: This boolean setting, when set to true (the default), tells OpenHands to run as the OpenHands user. Running as a specific user is important for security.
  • runtime: This specifies the runtime environment, which is "docker" by default. OpenHands currently primarily uses Docker for its runtime environment. Understanding the runtime environment is crucial for troubleshooting and advanced configurations.
  • default_agent: This sets the name of the default agent to use. The default is "CodeActAgent". Agents are the core logic components of OpenHands, and choosing the right agent is crucial for achieving your goals.
  • jwt_secret: This is a crucial setting for security. It's the secret key used for JSON Web Token (JWT) authentication. The default value is uuid.uuid4().hex, which generates a random UUID. However, you should absolutely set this to your own unique and secure value in a production environment. A strong JWT secret is vital for protecting your OpenHands instance.

LLM Configuration ([llm])

The [llm] section is where you configure the Large Language Model (LLM) that OpenHands uses. This is where you'll specify things like API keys, model selection, and retry settings. To use these with Docker, you'll pass them in as environment variables prefixed with LLM_, like -e LLM_NUM_RETRIES.

Custom LLM Configurations: For development setups, you can even define custom named LLM configurations. This lets you easily switch between different models or settings for different tasks. We'll touch on this briefly, but you can find more details in the Custom LLM Configurations documentation.

AWS Credentials

If you're using an LLM that requires AWS credentials, you'll need to configure these settings:

  • aws_access_key_id: Your AWS access key ID.
  • aws_region_name: The AWS region you're using.
  • aws_secret_access_key: Your AWS secret access key.

It's crucial to handle these credentials securely, ideally using environment variables or a secure configuration management system.

API Configuration

These settings control how OpenHands interacts with the LLM's API:

  • api_key: The API key to use for authentication. Always protect your API key and avoid hardcoding it directly in your configuration.
  • base_url: The base URL for the API. This is usually specific to the LLM provider.
  • api_version: The API version to use, if applicable.
  • input_cost_per_token: The cost per input token for the LLM. This is used for budgeting and cost tracking.
  • output_cost_per_token: The cost per output token for the LLM. Accurate cost tracking is essential for managing LLM usage.

Custom LLM Provider

  • custom_llm_provider: If you're using a custom LLM provider, you can specify it here. This allows you to integrate OpenHands with less common LLMs or your own in-house models. Flexibility in LLM provider selection is a key advantage of OpenHands.

Message Handling

  • max_message_chars: This sets the approximate maximum number of characters in the content of an event included in the prompt to the LLM. Larger observations are truncated. Limiting message size helps prevent context overload and reduces token usage.
  • max_input_tokens: The maximum number of input tokens for the LLM. Understanding token limits is crucial for avoiding errors and optimizing performance.
  • max_output_tokens: The maximum number of output tokens for the LLM. Controlling output token limits helps manage costs and prevent overly verbose responses.

Model Selection

  • model: This is where you specify the LLM model to use. The default is "claude-3-5-sonnet-20241022". Choosing the right model depends on your specific needs and budget. Some models are better suited for certain tasks than others.

Retrying

These settings control how OpenHands handles API request retries:

  • num_retries: The number of retries to attempt. The default is 8.
  • retry_max_wait: The maximum wait time (in seconds) between retry attempts. The default is 120.
  • retry_min_wait: The minimum wait time (in seconds) between retry attempts. The default is 15.
  • retry_multiplier: The multiplier for exponential backoff calculation. The default is 2.0.

These settings implement an exponential backoff strategy, which helps handle transient API errors gracefully. Proper retry configuration is important for reliability.

Advanced Options

  • drop_params: If set to true, OpenHands will drop any unmapped (unsupported) parameters without causing an exception. This can be useful for compatibility with different LLM APIs.
  • caching_prompt: If set to true (the default), OpenHands will use the prompt caching feature if it's provided by the LLM and supported. Prompt caching can significantly improve performance.
  • ollama_base_url: The base URL for the OLLAMA API, if you're using OLLAMA. OLLAMA integration provides a way to run LLMs locally.
  • temperature: The temperature for the API. A higher temperature leads to more random and creative outputs, while a lower temperature leads to more deterministic outputs. Adjusting the temperature allows you to control the creativity of the LLM.
  • timeout: The timeout for the API, in seconds. Setting a timeout prevents requests from hanging indefinitely.
  • top_p: The top-p value for the API. This is another way to control the randomness of the output. Experimenting with top_p can help you fine-tune the LLM's behavior.
  • disable_vision: If the model is vision-capable, this option allows you to disable image processing. This is useful for cost reduction if you don't need image processing. Disabling vision can save you money when it's not required.

Agent Configuration ([agent] and [agent.<agent_name>])

The [agent] and [agent.<agent_name>] sections let you configure the behavior of OpenHands agents. Agents are the core components that execute tasks, so configuring them correctly is essential for achieving your goals.

LLM Configuration

  • llm_config: This specifies the name of the LLM configuration group to use. The default is 'your-llm-config-group'. You can define different LLM configuration groups in your config.toml and switch between them easily. Using LLM configuration groups makes it easy to manage different LLM settings for different agents or tasks.

ActionSpace Configuration

  • function_calling: This boolean setting enables or disables function calling. Function calling allows the LLM to call external functions or tools, which significantly expands its capabilities. The default is true. Enabling function calling unlocks a wide range of possibilities.
  • enable_browsing: This enables or disables the browsing delegate in the action space. The browsing delegate allows the agent to browse the web, which can be useful for gathering information or interacting with web-based services. This only works if function calling is enabled. Enabling browsing allows the agent to access the vast resources of the internet.
  • enable_llm_editor: This enables or disables the LLM editor in the action space. The LLM editor allows the agent to edit text using the LLM, which can be useful for tasks like code generation or document editing. This also only works if function calling is enabled. Enabling the LLM editor expands the agent's ability to manipulate text.
  • enable_jupyter: This enables or disables Jupyter integration in the action space. Jupyter integration allows the agent to execute code in Jupyter notebooks, which can be useful for data analysis or scientific computing. Enabling Jupyter allows the agent to leverage the power of Jupyter notebooks.
  • enable_history_truncation: This determines whether the history should be truncated to continue the session when hitting the LLM context length limit. Enabling history truncation helps manage long-running sessions.

Microagent Usage

  • enable_prompt_extensions: This boolean setting enables or disables the use of microagents. Microagents are small, specialized agents that can be used to extend the capabilities of the main agent. The default is true. Enabling microagents allows for more modular and flexible agent design.
  • disabled_microagents: This is a list of microagents to disable. This allows you to selectively disable certain microagents if they're not needed or are causing issues. Disabling specific microagents can help optimize performance and prevent unwanted behavior.

Sandbox Configuration ([sandbox])

The [sandbox] section controls the configuration of the OpenHands sandbox, which is a secure environment for executing code. These settings are crucial for security and resource management. To use these with Docker, you'll pass them in as environment variables prefixed with SANDBOX_, like -e SANDBOX_TIMEOUT.

Execution

  • timeout: This sets the sandbox timeout in seconds. If a process runs longer than this, it will be terminated. The default is 120 seconds. Setting a timeout is a critical security measure to prevent runaway processes.
  • user_id: This specifies the user ID to use for the sandbox. The default is 1000. Using a specific user ID enhances security by isolating processes within the sandbox.

Container Image

  • base_container_image: This is the container image to use for the sandbox. The default is "nikolaik/python-nodejs:python3.12-nodejs22". This image should contain the necessary dependencies for your tasks. Choosing the right container image is essential for compatibility and performance.

Networking

  • use_host_network: If set to true, the sandbox will use the host network. This can be useful for certain applications, but it also reduces security. The default is false. Using the host network should be done with caution.
  • runtime_binding_address: This specifies the binding address for the runtime ports. It determines which network interface on the host machine Docker should bind the runtime ports to. The default is 0.0.0.0, which means it will bind to all interfaces. Understanding runtime binding addresses is important for networking configurations.

Linting and Plugins

  • enable_auto_lint: If set to true, auto-linting will be enabled after editing code. This helps ensure code quality and consistency. Enabling auto-linting is a good practice for code development.
  • initialize_plugins: This determines whether plugins should be initialized. The default is true. Initializing plugins allows you to extend OpenHands' functionality.

Dependencies and Environment

  • runtime_extra_deps: This allows you to specify extra dependencies to install in the runtime image. This is useful if your tasks require libraries that are not included in the base container image.
  • runtime_startup_env_vars: This allows you to set environment variables at the launch of the runtime. This can be used to configure the environment for your tasks. Setting environment variables is a common way to configure applications.

Evaluation

  • browsergym_eval_env: This specifies the BrowserGym environment to use for evaluation. BrowserGym is a framework for evaluating agents in web browser environments. Using BrowserGym allows you to test your agents in realistic scenarios.

Security Configuration ([security])

The [security] section is where you configure security-related settings for OpenHands. These settings are crucial for protecting your system and data. To use these with Docker, you'll pass them in as environment variables prefixed with SECURITY_, like -e SECURITY_CONFIRMATION_MODE.

Confirmation Mode

  • confirmation_mode: If set to true, OpenHands will require confirmation before executing certain actions. This adds an extra layer of security by preventing accidental or malicious actions. The default is false. Enabling confirmation mode is a good practice for security-sensitive environments.

Security Analyzer

  • security_analyzer: This specifies the security analyzer to use. A security analyzer can help identify potential vulnerabilities in your code or configuration. Using a security analyzer enhances your system's security posture.

Final Thoughts

Alright guys, that was a deep dive into the OpenHands config.toml file! It might seem like a lot, but understanding these configurations is the key to unlocking the full potential of OpenHands. Remember to adjust these settings carefully, especially the memory, security, and network-related ones. And keep in mind that these options might change in future versions, so always refer to the official documentation for the latest info.

Key Takeaways:

  • The config.toml file is your control panel for OpenHands.
  • Pay close attention to security settings, especially jwt_secret and sandbox configurations.
  • Customize LLM settings to optimize performance and cost.
  • Experiment with agent configurations to tailor their behavior to your needs.
  • Always refer to the official documentation for the most up-to-date information.

By mastering the config.toml file, you'll be well on your way to becoming an OpenHands pro. Happy configuring!