Skip to content

docs: add Sandbox Grouping Strategy section to Application Settings #514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jpelletier1 wants to merge 2 commits into
base: main
Choose a base branch
from
+28 −1
Open

docs: add Sandbox Grouping Strategy section to Application Settings #514

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3147d3
docs: add Sandbox Grouping Strategy section to Application Settings
jpelletier1 May 20, 2026
007f21d
Update openhands/usage/settings/application-settings.mdx
jpelletier1 May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion openhands/usage/settings/application-settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,41 @@ description: Configure application-level settings for OpenHands.
## Overview

The Application settings allows you to customize various application-level behaviors in OpenHands, including
language preferences, notification settings, custom Git author configuration and more.
language preferences, notification settings, sandbox grouping strategy, custom Git author configuration and more.

## Setting Maximum Budget Per Conversation

To limit spending, go to `Settings > Application` and set a maximum budget per conversation (in USD)
in the `Maximum Budget Per Conversation` field. OpenHands will stop the conversation once the budget is reached, but
you can choose to continue the conversation with a prompt.

## Sandbox Grouping Strategy

The **Sandbox Grouping Strategy** setting controls how new conversations are assigned to sandboxes. A sandbox is an isolated environment where OpenHands executes code and commands. This setting lets you choose whether each conversation gets its own dedicated sandbox or whether conversations share sandboxes.

To configure sandbox grouping:

1. Navigate to `Settings > Application`
2. Locate the **Sandbox Grouping Strategy** dropdown
3. Select your preferred strategy
4. Click `Save Changes`

### Available Strategies

| Strategy | Description |
|----------|-------------|
| **No Grouping** | Creates a new sandbox for each conversation. This is the default behavior and provides maximum isolation between conversations. |
| **Group by Newest** | Adds new conversations to the most recently created sandbox. Useful when you want to continue working in the same environment across multiple conversations. |
| **Least Recently Used** | Adds new conversations to the oldest (least recently used) sandbox. This helps distribute work across sandboxes and can reuse existing environments. |
Comment thread
jpelletier1 marked this conversation as resolved.
| **Fewest Conversations** | Adds new conversations to the sandbox with the fewest active conversations. This provides load balancing across your sandboxes. |
| **Add to Any** | Uses the first available sandbox for new conversations (any sandbox that exists in your environment). This is the most flexible option and optimizes for sandbox reuse. |

<Note>
Choosing a grouping strategy other than "No Grouping" allows conversations to share environment state,
installed dependencies, and file system changes. This can speed up workflows but means changes from one
conversation may be visible to others in the same sandbox.
</Note>

## Git Author Settings

OpenHands provides the ability to customize the Git author information used when making commits and creating
Expand Down
Loading