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 1 commit into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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. |
Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: The term "oldest" is ambiguous. Consider rewording for clarity:

Suggested change
| **Least Recently Used** | Adds new conversations to the oldest (least recently used) sandbox. This helps distribute work across sandboxes and can reuse existing environments. |
| **Least Recently Used** | Adds new conversations to the sandbox that was least recently accessed (longest time since last use). This helps distribute work across sandboxes and can reuse existing environments. |

| **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. This is the most flexible option and optimizes for sandbox reuse. |
Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: "First available sandbox" is vague. What makes a sandbox available vs. unavailable? Consider clarifying:

Suggested change
| **Add to Any** | Uses the first available sandbox for new conversations. This is the most flexible option and optimizes for sandbox reuse. |
| **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. |

Alternatively, if there are specific conditions that make a sandbox unavailable (e.g., being terminated, exceeding capacity), those should be documented.

Comment on lines +30 to +38
Copy link
Copy Markdown
Contributor

@all-hands-bot all-hands-bot May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: Consider adding a brief "When to Use" column or section to help users choose the right strategy. For example:

  • No Grouping: When isolation is critical or debugging issues specific to one conversation
  • Group by Newest: When iterating on the same project across multiple conversations
  • Least Recently Used: When you want even distribution and have multiple long-running sandboxes
  • Fewest Conversations: When you need automatic load balancing across sandboxes
  • Add to Any: When sandbox reuse is more important than specific distribution logic

This guidance would help users make informed decisions rather than guessing based on strategy names alone.


<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