- Server route already returns a list[VSCodeInstanceInfo]
- VsCodeRuntime now expects a list and validates shape
- Updated tests to mock list responses consistently
Co-authored-by: OpenHands-GPT-5 <openhands@all-hands.dev>
- IterationControlFlag.reached_limit now compares current_value >= max_value
so tests expecting limit detection and extensions pass
- VsCodeRuntime._get_available_vscode_instances accepts both list and
{"instances": [...]} responses from server for backward/forward compatibility
Co-authored-by: OpenHands-GPT-5 <openhands@all-hands.dev>
- Include VSCode API routes only when AppMode is OSS, aligning with app-mode gating
alongside Git routes.
- Conflicts reconciled with main: kept OSS-gated inclusion to match current server
composition and PR intent.
Co-authored-by: OpenHands-GPT-5 <openhands@all-hands.dev>
Fixes mypy error in VsCodeRuntime by aligning status_callback signature with Runtime and importing RuntimeStatus.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Merge VSCode extension ignore and test-results entries in .gitignore.
- In openhands/server/app.py import server_config and AppMode and conditionally include git routes for OSS mode; also include vscode routes.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Resolved conflicts by taking vscode-runtime versions for VSCode-related files:
- package.json: Kept runtime features (testConnection command, serverUrl config)
- extension.ts: Kept runtime services and connection logic
- README.md: Kept unified launcher + runtime documentation
- test/suite/index.ts: Kept modern async/await glob usage
Took main version for:
- local_runtime.py: Use sys.executable instead of poetry for Jupyter check
The file was causing an import collision on Windows,
where the would try to import from this
file instead of the installed library. This was causing
the server process to crash and the tests to fail.
This commit renames to to avoid this
name collision and updates all references to the old filename.
Co-authored-by: Gemini
The previous implementation of the jupyter dependency check in the
LocalRuntime used with . This was
causing the server process to die on Windows, leading to test failures.
This change refactors the subprocess call to avoid using the shell,
making it more robust and secure, especially on Windows. This resolves
the CI failures for LocalRuntime tests on the Windows platform.
Co-authored-by: Gemini
- Fix trailing whitespace in test_coverage_analysis.md
- Fix end of file issues
- Apply ruff fixes to ensure all Python code passes linting
All pre-commit hooks now pass successfully.
✅ ALL TESTS NOW PASSING (31/31)
FIXES APPLIED:
🔧 Updated subprocess call count expectations (0→1 for --list-extensions)
🔧 Fixed Windsurf command detection (windsurf→surf)
🔧 Updated error message expectations (attempt→success flag)
🔧 Fixed flag creation behavior (no flag on failure = retry logic)
🔧 Updated bundled installation test patterns (1→2 subprocess calls)
BEHAVIORAL CHANGES VALIDATED:
✅ Extension detection via --list-extensions (always called first)
✅ Success-only flag creation (no flag on failure allows retry)
✅ Proper error handling and user messaging
✅ Windsurf vs VS Code command detection
✅ GitHub + bundled installation fallback patterns
COVERAGE STATUS:
📊 67% coverage (42 lines missing)
🎯 All critical new functionality fully tested
🧪 31 comprehensive tests covering all scenarios
The test suite now accurately reflects the new user-friendly
retry logic and success-based flagging behavior.
MAJOR UX IMPROVEMENT:
- Only create flag file on SUCCESS, not on failure
- Check if extension is already installed before attempting installation
- Allow automatic retry if previous installation failed
- No more manual flag file deletion needed
NEW BEHAVIOR:
- ✅ Extension already installed → detect and mark as successful
- ✅ Installation succeeds → create flag, don't retry
- ✅ Installation fails → no flag, will retry next time
- ✅ User installs VS Code later → automatic retry works
- ✅ User fixes PATH/permissions → automatic retry works
TECHNICAL CHANGES:
- Add _is_extension_installed() to check via --list-extensions
- Add _mark_installation_successful() helper
- Change flag file name from _install_attempted to _installed
- Update tests for new subprocess call patterns
- Add test for extension already installed detection
This makes the installation much more user-friendly and follows
standard practices used by package managers and IDE extensions.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Extract GitHub installation logic into _attempt_github_install()
- Extract bundled VSIX installation logic into _attempt_bundled_install()
- Improve code readability and maintainability
- Each method now has clear responsibility and return values
- Main function is now much cleaner and easier to follow
- All existing functionality preserved, all tests still pass
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Fixed quote consistency (double to single quotes)
- Applied line wrapping for long argument lists
- Improved code formatting per ruff standards
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Updated all tests to expect no marketplace installation attempts
- Simplified error message expectations to match new behavior
- All 24 tests now pass with marketplace installation disabled
- Applied linter formatting fixes
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Fixed control flow bug where return statement prevented finally block execution
- Ensured temporary GitHub VSIX files are always cleaned up after installation
- Updated test to properly mock os.path.exists for cleanup verification
The issue was that when GitHub installation succeeded, the function would return
immediately before the finally block could execute to clean up the downloaded
temporary file. Now we use a success flag and return after cleanup.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Convert single quotes to double quotes for consistency
- Clean up if-else structure formatting
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Use npx vsce instead of global vsce command to ensure the tool is available
from node_modules/.bin on Windows CI environments where global packages
may not be properly configured.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Remove unnecessary try-catch around fs.existsSync() which doesn't throw exceptions
- Fix Windows virtual environment activation to use PowerShell syntax with Activate.ps1
- Improve cross-platform path handling using path.join() instead of string concatenation
- Reorganize code for better separation of platform-specific logic
- Add detailed comments explaining Windows activation approach and limitations
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Implement contextual messaging for saved files in 'Start Conversation with File Context' command:
- Saved files now use contextual task messages instead of --file flag
- Message format: 'The user has tagged a file [path]. Please read and understand...'
- Maintains original natural language for untitled files: 'User opened an untitled file...'
- Updated tests to verify new contextual messaging behavior
- Follows same pattern as selection context for consistent user experience
This addresses reviewer feedback to provide contextual messaging for file operations
similar to the Python CLI implementation.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Implemented contextual messaging with createFileContextMessage() and createSelectionContextMessage() helpers
- Added Shell Integration support for better command tracking when available
- Conservative terminal reuse approach - only reuses terminals known to be idle to avoid interrupting user processes
- Idle terminal tracking through Shell Integration execution events
- Proper fallback to sendText when Shell Integration unavailable
- Fixed TypeScript compilation errors in Shell Integration tests with proper mock object properties
- Updated test setup for Mocha compatibility (setup() instead of beforeEach())
- All 16 tests now passing including contextual messaging and Shell Integration functionality
- Verified line number conversion (+1) is correct per VSCode API documentation (0-based to 1-based for human readability)
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Updated Node.js requirement from >=16 to >=18 to match the frontend's
actual usage (18.20.1 via Volta), ensuring consistency across the project.
Changes:
- package.json: Added Node.js >=18.0.0 engine requirement
- build.py: Updated version check to require Node.js >=18
- README.md: Updated documentation to reflect >=18 requirement
- Error messages: Updated to show correct version requirement
This aligns with the frontend's practical Node.js version while
maintaining the optional build fallback for older versions.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
The previous logic incorrectly skipped building if a .vsix file existed,
which prevented rebuilding during development. Now the logic is:
1. Always try to build if Node.js >= 16 is available
2. Only use pre-built .vsix as fallback when Node.js < 16 or missing
3. Only skip building when SKIP_VSCODE_BUILD is explicitly set
This ensures:
- Developers can rebuild extensions during development
- Users with old Node.js get the pre-built fallback
- The build process works correctly for fresh installs
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Based on the reviewer's error output showing many VSCode extension
dependencies require Node.js >= 16 or >= 18, update the version check
from >= 14 to >= 16 for more accurate compatibility.
This addresses the specific error with Node.js v12.22.9 that was failing
due to dependencies requiring newer Node.js versions.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add Node.js version check (requires >= 14)
- Use pre-built .vsix file when Node.js is too old
- Add SKIP_VSCODE_BUILD environment variable option
- Gracefully handle build failures
- Update documentation with build options
This fixes installation issues on systems with Node.js < 14 by falling back
to the pre-built extension instead of failing the entire installation.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Correct Task 2 status from completed to in-progress
- Maintain focus on VSCode Runtime refinement rather than moving to Task 3
- Update next steps to show rebase/integration completed but runtime work ongoing
- Accurately reflect that we're working on making VSCode Runtime robust and reliable
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Fix async Promise executor pattern in test suite
- Fix class method reference issues (RuntimeActionHandler -> VSCodeRuntimeActionHandler)
- Fix explicit any types to unknown in error handlers
- Remove unused mockSocket variable in tests
- Fix trailing whitespace in markdown file
All TypeScript compilation errors resolved, extension now compiles successfully.
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
Since we now use openhands-types directly from GitHub repository
via git dependency, the local packages/types copy is no longer needed.
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
- Add openhands-types as git dependency from GitHub repository
- Install openhands-types package with full TypeScript declarations
- Fix test/suite/index.ts to use modern glob API with named import
- Verify all type imports work correctly (OpenHandsParsedEvent, isOpenHandsAction)
- Confirm extension compiles and packages successfully
- Add comprehensive analysis document for openhands-types integration
This resolves the missing openhands-types dependency that was blocking
VSCode Runtime (Task 2) development. The extension can now properly
validate and handle OpenHands events and actions.
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
BREAKTHROUGH: Solved the @openhands/types package issue that was blocking VSCode extension testing!
## Problem Solved:
- Module resolution failure: 'Cannot find module packages/types/dist/core/base'
- File-based package linking failed in VSCode test environment
- Module format mismatch between ES modules and CommonJS
## Solution Implemented:
1. **Package Renamed**: @openhands/types → openhands-types (npm compatible)
2. **Dual-Format Package**: Support both CommonJS (.cjs) and ES modules (.js)
3. **npm link**: Established proper symlink between packages/types and extension
4. **Import Path Fixes**: Fixed CommonJS require statements to use .cjs extensions
5. **Build Automation**: Scripts handle dual builds and file renaming
## Technical Changes:
- packages/types/package.json: Dual exports with proper file extensions
- packages/types/tsconfig.cjs.json: CommonJS build configuration
- packages/types/fix-cjs-imports.js: Script to fix import paths
- VSCode extension: Updated dependency to 'openhands-types': '^0.1.0'
- Import statements: Updated in socket-service.ts and runtime-action-handler.ts
## Verification:
✅ Extension compiles successfully without errors
✅ Tests run properly (20 tests passing)
✅ Module resolution working in both dev and test environments
✅ npm link functioning with proper symlink
## Status:
- Module resolution issue: COMPLETELY SOLVED
- Extension testing: UNBLOCKED
- Remaining test failures: Unrelated network/mocking issues
This resolves the core TypeScript types package issue that was preventing
VSCode extension testing and development.
Co-authored-by: openhands <openhands@all-hands.dev>
Auto-fixed formatting and style issues in VSCode extension source files
using eslint and prettier.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add socket-service.test.ts with 3 passing tests for basic functionality, VSCode API access, and fetch mocking
- Add runtime-action-handler.test.ts with 3 passing tests for basic functionality, workspace API, and workspace mocking
- Establish TypeScript test framework for VSCode extension services
- Implement proper mocking patterns for VSCode APIs
- Create test infrastructure ready for future service testing expansion
- All new tests compile and run successfully (7/7 passing)
- Update task.md to mark Phase 4.3 as completed
Technical achievements:
- Successfully created TypeScript test framework avoiding complex import issues
- Validated VSCode API mocking capabilities for future comprehensive testing
- Established foundation for testing SocketService and RuntimeActionHandler classes
OpenHands-Claude
✅ PHASE 3 COMPLETED: VsCodeRuntime Discovery & Error Handling
Dynamic Discovery System:
- Removed constructor dependencies for sio_server/socket_connection_id
- Added _get_available_vscode_instances() to query /api/vscode/instances
- Added _validate_vscode_connection() for health checking
- Added _discover_and_connect() for automatic VSCode instance discovery
- Gets sio_server from shared.py automatically (no injection needed)
Smart Connection Management:
- Lazy connection: only connects when actions need to be sent
- Connection validation before every action
- Automatic reconnection if VSCode instance becomes inactive
- Failover to alternative VSCode instances when available
- Comprehensive error handling with user-friendly messages
Enhanced Runtime Features:
- Works with standard AgentSession parameters (no special constructor args)
- Logs workspace path and capabilities on connection
- Continuous health monitoring of connections
- Graceful handling of disconnections and network issues
- Clear error messages when no VSCode instances available
Architecture Achievement:
- Complete end-to-end lazy connection pattern implementation
- VSCode Extension registers → Server tracks → Runtime discovers → Actions flow
- Eliminated timing issues between extension connection and runtime creation
- Robust connection lifecycle management with automatic recovery
- Foundation ready for Phase 4 integration testing
Technical Details:
- Fixed mypy type errors for None checks and union types
- Added proper validation for socket_connection_id before use
- Enhanced error handling for sio_server None cases
- Maintained backward compatibility with existing test injection patterns
Next: Phase 4 - Integration testing and final validation of complete system
Co-authored-by: enyst <enyst@users.noreply.github.com>
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
✅ COMPLETED: Extension Lazy Connection Implementation
- Remove immediate initializeRuntime() call from activate()
- Add ConnectionStatus enum for tracking connection state
- Implement ensureConnected() function with lazy connection logic
- Modify all user commands to trigger connection on-demand
- Add openhands.testConnection command for manual testing
- Replace eager connection with user-triggered connection flow
🔧 TECHNICAL CHANGES:
- Extension now activates without connecting to server
- Connection only happens when user runs OpenHands commands
- Comprehensive error handling with user-friendly messages
- Retry and configuration options in error dialogs
- Connection status tracking prevents duplicate attempts
🎯 BENEFITS:
- Eliminates timing dependency (server doesn't need to be running on VSCode start)
- Matches user mental model (connect when using OpenHands)
- Better error handling and user feedback
- Resource efficient (no background connections)
📋 NEXT: Phase 2 - Server Registration System
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
BREAKTHROUGH: Identified fundamental timing issue with immediate connection:
- VSCode Extension activates when VSCode starts
- But OpenHands server might not be running yet!
- Extension fails to connect and becomes unusable
NEW APPROACH: Lazy Connection Pattern
- Extension activates but doesn't connect immediately
- Only connects when user runs OpenHands commands
- Matches user mental model and eliminates timing dependencies
- Simpler, more resource-efficient implementation
Next: Implement lazy connection in extension activation
Co-authored-by: OpenHands-Claude <openhands-claude@all-hands.dev>
Removed migration section since code consolidation is done.
Now focused on implementing the Runtime Registration Pattern:
- VSCode registration API endpoint
- Extension registration after Socket.IO connection
- VsCodeRuntime connection discovery
- End-to-end coordination testing
- Architecture breakthrough: Socket.IO approach is brilliant, not hallucinated
- Identified real problems: connection coordination, not fundamental architecture
- Proposed solution: Runtime Registration Pattern for connection discovery
- Migration plan: consolidate extension code from old scaffolding to main extension
- Next steps: migrate files, implement registration API, test coordination
Key findings:
- Socket.IO architecture is actually brilliant and correct
- VSCode Extension acts like another frontend client (like web UI)
- Main issue: VsCodeRuntime needs socket_connection_id but has no way to get it
- AgentSession only passes standard runtime params, missing VSCode-specific ones
Proposed solution: Runtime Registration Pattern
- VSCode Extension registers itself with OpenHands server after connecting
- Server maintains registry: socket_connection_id → VSCode instance info
- VsCodeRuntime queries registry to find available connections
- Clean separation: Extension handles connection, Runtime handles execution
This solves the coordination problem without changing core architecture!
- VSCode Extension acts like another frontend client (like web UI)
- Main Socket.IO server acts as message broker
- VsCodeRuntime routes events via socket_connection_id
- Architecture reuses existing OpenHands infrastructure elegantly
- Real issues are connection timing and coordination, not architecture
Document the successful completion of the VSCode runtime migration:
- All 4 phases completed successfully
- Extension functionality unified (launcher + runtime)
- Old extension cleanly removed
- Documentation updated
- Ready for testing and deployment
This summary provides a comprehensive overview of what was accomplished
during the migration process.
Major integration milestone:
- Add imports for SocketService and VSCodeRuntimeActionHandler
- Add runtime initialization function with server URL configuration
- Integrate runtime startup in activate() function
- Add proper cleanup in deactivate() function
- Successfully compile and package unified extension
The extension now combines:
1. Launcher functionality (context menu commands)
2. Runtime functionality (backend communication and action execution)
Testing results:
- ✅ TypeScript compilation successful (npm run compile)
- ✅ Extension packaging successful (npm run package-vsix)
- 🔄 Manual testing in VSCode pending
Next: Phase 4 cleanup of old runtime extension files.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add ~/.openhands/microagents/ as a microagent source directory
- User microagents are loaded after global ones, allowing overrides
- Automatically create user microagents directory if it doesn't exist
- Add comprehensive unit tests for user microagent functionality
- Handle errors gracefully when loading user microagents
This allows users to store personal/local microagents in their user
directory instead of keeping uncommitted files in repository working
directories, preventing accidental loss during git operations.
Co-authored-by: openhands <openhands@all-hands.dev>
- Fix VsCodeRuntime constructor to match standard runtime interface
- Add missing abstract methods with correct signatures: connect, copy_from, copy_to, get_mcp_config, list_files
- Add VSCode runtime to test framework in conftest.py
- Add VSCode runtime tests to CI workflow
- Create comprehensive task analysis in vscode_runtime_task.md
- Update vscode.md with current implementation status
The VSCode runtime now properly integrates with the existing test infrastructure
and returns appropriate errors when no VSCode extension is connected.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
✅ Added event serialization support:
- Import event_to_dict and event_from_dict from openhands.events.serialization
- Replace manual event payload creation with proper event_to_dict()
- Replace manual observation construction with event_from_dict()
✅ Benefits:
- Ensures consistent JSON serialization format across all runtimes
- Handles all action/observation types automatically
- Proper handling of complex fields (timestamps, enums, metadata)
- Maintains compatibility with existing event stream format
- Reduces code duplication and potential serialization bugs
✅ Socket.IO communication now uses:
- Outgoing: event_to_dict(action) → JSON → VSCode extension
- Incoming: JSON → event_from_dict(observation_event) → Observation
This makes the VSCode runtime fully compatible with OpenHands event
serialization standards and ready for production use.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Major fixes applied:
✅ Removed hallucinated actions:
- Deleted mkdir(), rmdir(), rm() methods - these action types don't exist
- Directory operations should use CmdRunAction or FileEditAction
✅ Added missing required abstract methods:
- edit() for FileEditAction
- browse_interactive() for BrowseInteractiveAction
- call_tool_mcp() for MCPAction
✅ Fixed method signatures:
- All methods now match Runtime base class exactly
- Added _run_async_action() helper for async operations in sync context
✅ Removed non-standard methods:
- Deleted recall(), finish(), send_message() - these are agent-level actions
✅ Fixed imports and observations:
- Added missing Action import and all required action/observation types
- Added support for FileEditObservation, BrowserOutputObservation, etc.
- Fixed observation constructors with correct parameters
✅ Fixed event payload and logging:
- Use action.__class__.__name__ and action.__dict__
- Fixed logger.warn() to logger.warning()
- Fixed mypy type errors with proper type assertions
The runtime now correctly implements all required abstract methods with only
actual OpenHands actions. Socket.IO architecture remains sound. Ready for
integration testing with VSCode extension.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Identified hallucinated actions: mkdir, rmdir, rm don't exist in OpenHands
- Directory operations should use CmdRunAction or FileEditAction
- Missing required abstract methods: edit, browse_interactive, call_tool_mcp
- Wrong method signatures: some async methods should be sync
- Scope issues: implementing agent-level actions instead of execution actions
- Socket.IO architecture is correct, but action handling needs fixes
- Documented actual OpenHands actions vs hallucinated ones
The runtime needs to implement only the actions that actually exist in openhands.events.
- Corrected analysis to recognize existing Socket.IO infrastructure
- Removed incorrect assumptions about missing infrastructure
- Updated architecture documentation to show proper event flow
- Changed assessment from 'fundamental issues' to 'implementation details'
- Documented proper integration with existing OpenHands Socket.IO server
The VSCode runtime approach is architecturally sound and leverages existing infrastructure correctly.
- Add ~/.openhands/microagents/ as a microagent source directory
- User microagents are loaded after global ones, allowing overrides
- Automatically create user microagents directory if it doesn't exist
- Add comprehensive unit tests for user microagent functionality
- Handle errors gracefully when loading user microagents
This allows users to store personal/local microagents in their user
directory instead of keeping uncommitted files in repository working
directories, preventing accidental loss during git operations.
Co-authored-by: openhands <openhands@all-hands.dev>
- Fix VsCodeRuntime constructor to match standard runtime interface
- Add missing abstract methods with correct signatures: connect, copy_from, copy_to, get_mcp_config, list_files
- Add VSCode runtime to test framework in conftest.py
- Add VSCode runtime tests to CI workflow
- Create comprehensive task analysis in vscode_runtime_task.md
- Update vscode.md with current implementation status
The VSCode runtime now properly integrates with the existing test infrastructure
and returns appropriate errors when no VSCode extension is connected.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Fix VsCodeRuntime constructor to match standard runtime interface
- Add missing abstract methods with correct signatures: connect, copy_from, copy_to, get_mcp_config, list_files
- Add VSCode runtime to test framework in conftest.py
- Add VSCode runtime tests to CI workflow
- Create comprehensive task analysis in vscode_runtime_task.md
- Update vscode.md with current implementation status
The VSCode runtime now properly integrates with the existing test infrastructure
and returns appropriate errors when no VSCode extension is connected.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
✅ Added event serialization support:
- Import event_to_dict and event_from_dict from openhands.events.serialization
- Replace manual event payload creation with proper event_to_dict()
- Replace manual observation construction with event_from_dict()
✅ Benefits:
- Ensures consistent JSON serialization format across all runtimes
- Handles all action/observation types automatically
- Proper handling of complex fields (timestamps, enums, metadata)
- Maintains compatibility with existing event stream format
- Reduces code duplication and potential serialization bugs
✅ Socket.IO communication now uses:
- Outgoing: event_to_dict(action) → JSON → VSCode extension
- Incoming: JSON → event_from_dict(observation_event) → Observation
This makes the VSCode runtime fully compatible with OpenHands event
serialization standards and ready for production use.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
Major fixes applied:
✅ Removed hallucinated actions:
- Deleted mkdir(), rmdir(), rm() methods - these action types don't exist
- Directory operations should use CmdRunAction or FileEditAction
✅ Added missing required abstract methods:
- edit() for FileEditAction
- browse_interactive() for BrowseInteractiveAction
- call_tool_mcp() for MCPAction
✅ Fixed method signatures:
- All methods now match Runtime base class exactly
- Added _run_async_action() helper for async operations in sync context
✅ Removed non-standard methods:
- Deleted recall(), finish(), send_message() - these are agent-level actions
✅ Fixed imports and observations:
- Added missing Action import and all required action/observation types
- Added support for FileEditObservation, BrowserOutputObservation, etc.
- Fixed observation constructors with correct parameters
✅ Fixed event payload and logging:
- Use action.__class__.__name__ and action.__dict__
- Fixed logger.warn() to logger.warning()
- Fixed mypy type errors with proper type assertions
The runtime now correctly implements all required abstract methods with only
actual OpenHands actions. Socket.IO architecture remains sound. Ready for
integration testing with VSCode extension.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Identified hallucinated actions: mkdir, rmdir, rm don't exist in OpenHands
- Directory operations should use CmdRunAction or FileEditAction
- Missing required abstract methods: edit, browse_interactive, call_tool_mcp
- Wrong method signatures: some async methods should be sync
- Scope issues: implementing agent-level actions instead of execution actions
- Socket.IO architecture is correct, but action handling needs fixes
- Documented actual OpenHands actions vs hallucinated ones
The runtime needs to implement only the actions that actually exist in openhands.events.
- Corrected analysis to recognize existing Socket.IO infrastructure
- Removed incorrect assumptions about missing infrastructure
- Updated architecture documentation to show proper event flow
- Changed assessment from 'fundamental issues' to 'implementation details'
- Documented proper integration with existing OpenHands Socket.IO server
The VSCode runtime approach is architecturally sound and leverages existing infrastructure correctly.
- Add OpenHands submenu to context menu for cleaner organization
- Group 'Start with File Content' and 'Start with Selected Text' commands
- Use shorter titles in context menu while preserving full descriptive names in Command Palette
- Leverage category field to automatically prefix commands with 'OpenHands:' in Ctrl+Shift+P
Co-authored-by: openhands <openhands@all-hands.dev>
- Change from 'OpenHands 14:32:45' to 'OpenHands 14:32'
- More human-friendly and cleaner terminal tab names
- Minute precision is sufficient for terminal identification
- VSCode handles duplicate names gracefully if needed
Co-authored-by: openhands <openhands@all-hands.dev>
- build.py is essential: runs npm install and npm run package-vsix
- Creates the .vsix file during Poetry build process
- Without it, there would be no .vsix file to include in package
- This is a necessary part of VSCode extension integration
Co-authored-by: openhands <openhands@all-hands.dev>
- Keep only essential change: include .vsix file in package
- Revert unnecessary changes to packages structure and dependencies
- Remove pytest from main dependencies (belongs in dev.dependencies)
- Remove custom build script (not needed for this PR)
- Cleaner, focused changes for VSCode extension integration
Co-authored-by: openhands <openhands@all-hands.dev>
- Moved development planning document to ~/.openhands/microagents/plan-vscode-integration.md
- PLAN.md was useful during development but doesn't belong in production extension
- Keeps repository clean for end users while preserving development history
Co-authored-by: openhands <openhands@all-hands.dev>
- Remove error messages for missing editor/file/selection contexts
- All commands now gracefully fallback to starting OpenHands without task
- Better user experience: clicking any command always starts OpenHands
- Commands behavior:
* startConversation: no task (unchanged)
* startConversationWithFileContext: file content as task, or no task if no file/empty
* startConversationWithSelectionContext: selected text as task, or no task if no selection
Co-authored-by: openhands <openhands@all-hands.dev>
- Replace last DEBUG showErrorMessage with output channel logging
- Keep legitimate user-facing error messages as popups
- All debug info now goes to 'OpenHands Debug' output channel
Co-authored-by: openhands <openhands@all-hands.dev>
- Remove vscode.window.showErrorMessage() calls for debug information
- Add dedicated 'OpenHands Debug' output channel for development logging
- Debug messages now appear in Output panel instead of popup notifications
- Users won't be bothered by debug messages, but developers can still access them
- Follows VSCode extension best practices for logging
Co-authored-by: openhands <openhands@all-hands.dev>
This development-time analysis file has been moved to user microagents
directory (~/.openhands/microagents/) as it's not needed by other developers.
The analysis was useful during development but doesn't belong in the PR.
- Uncomment .vscode-test/ in .gitignore to prevent accidental commits
- These files are generated during extension testing and shouldn't be in version control
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add location info for public microagents in glossary
- Add comprehensive Microagents section to repo.md with:
- Types (public vs repository microagents)
- Loading behavior (frontmatter triggers vs always-loaded)
- Structure example with YAML frontmatter
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add comprehensive VSCode API documentation references as comments
- Include Shell Integration requirements and compatibility notes
- Preserve important development references in the codebase for future maintainers
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Move TERMINAL_REUSE_ANALYSIS.md to .openhands/microagents/vscode-terminal-reuse-analysis.md
- Update README.md with essential user-facing terminal management info
- Remove detailed development analysis from PR, keeping it for future reference
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Updated package.json engines.vscode from ^1.80.0 to ^1.98.2
- Updated @types/vscode dependency to ^1.98.2
- Updated README.md requirements section
- Updated PLAN.md documentation
- Regenerated package-lock.json automatically via npm install
This aligns our main VSCode extension with the runtime extensions
which already require VSCode 1.98.2+, ensuring consistency across
all VSCode integrations in the project.
Co-authored-by: openhands <openhands@all-hands.dev>
- Add VSCode extension linting command to pre-push checklist
- Document VSCode extension structure, setup, and commands
- Include linting, building, and testing commands for the extension
Co-authored-by: OpenHands <openhands@all-hands.dev>
- Add comprehensive linting setup adapted from frontend configuration
- Configure ESLint with airbnb-base rules for Node.js/VSCode extensions
- Add Prettier configuration matching frontend standards
- Include linting scripts in package.json (lint, lint:fix, typecheck)
- Add development dependencies for linting tools
- Update documentation with linting workflow and development guidelines
- Apply automatic formatting to all source files
- Configure special rules for test files and VSCode extension patterns
This ensures code quality consistency with the main OpenHands codebase.
Co-authored-by: OpenHands <openhands@all-hands.dev>
The previous implementation used probing to detect terminal status, which
could interrupt running CLI processes. This fix implements safe state
tracking that only reuses terminals where OpenHands commands have completed.
Key changes:
- Remove intrusive terminal probing that interrupted running processes
- Add safe state tracking using Set to track idle terminals
- Only reuse terminals that we know are safe (completed our commands)
- Use Shell Integration API for monitoring command completion
- Create new terminals when terminal state is unknown (safe fallback)
- Clean up terminal state tracking when terminals are closed
This ensures that running CLIs and other processes in terminals are never
interrupted when sending new tasks to OpenHands.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Add Shell Integration API support for smart terminal detection
- Implement terminal probing to check if terminals are idle
- Add graceful fallback to new terminal creation when Shell Integration unavailable
- Refactor code into modular functions for better maintainability
- Add comprehensive tests for new terminal reuse functionality
- Update README with new features and requirements
- Support cross-shell compatibility (bash, zsh, PowerShell, fish)
This implements the advanced terminal handling described in TERMINAL_REUSE_ANALYSIS.md,
providing intelligent terminal reuse while maintaining backward compatibility.
Co-authored-by: OpenHands-Gemini <openhands@all-hands.dev>
- Add comprehensive analysis of VSCode's Shell Integration capabilities
- Document intelligent terminal probing with execution.read() and executeCommand()
- Update recommendations to use Shell Integration with graceful fallback
- Replace outdated API limitations with current 2024/2025 capabilities
- Add implementation strategy with phases and code examples
- Include proper references to VSCode API documentation
Co-authored-by: Claude 3.5 Sonnet <claude-3-5-sonnet@anthropic.com>
The build script was trying to copy the VSIX file to the same location,
causing a SameFileError. Since the VSIX is already built in the correct
location (openhands/integrations/vscode/) and pyproject.toml includes
it from there, no copying is needed.
Changes:
- Remove unnecessary copy operation from build_vscode_extension()
- Remove unused shutil import and RESOURCES_DIR variable
- Simplify to just build and verify the VSIX exists
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
- Move VS Code extension from root-level openhands-vscode/ to openhands/integrations/vscode/
- Update pyproject.toml to include VSIX from new location: openhands/integrations/vscode/*.vsix
- Update CLI code to load VSIX from new path: integrations/vscode/
- Update build.py to build extension in new location
- Preserve file history using git mv operations
- Maintain VSIX bundling in PyPI package for CLI auto-installation
This reorganization improves architectural consistency by placing the VS Code
integration alongside other integrations rather than at the root level.
The VSIX file is excluded as it's a build artifact generated by build.py.
Co-authored-by: OpenHands-Claude <openhands@all-hands.dev>
stale-issue-message:'This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
stale-pr-message:'This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
days-before-stale:30
exempt-issue-labels:'tracked'
close-issue-message:'This issue was closed because it has been stalled for over 30 days with no activity.'
close-pr-message:'This PR was closed because it has been stalled for over 30 days with no activity.'
days-before-close:7
stale-issue-message:'This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.'
stale-pr-message:'This PR is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.'
days-before-stale:40
exempt-issue-labels:'roadmap'
close-issue-message:'This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.'
close-pr-message:'This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.'
@@ -19,6 +19,7 @@ Before pushing any changes, you MUST ensure that any lint errors or simple test
* If you've made changes to the backend, you should run `pre-commit run --config ./dev_config/python/.pre-commit-config.yaml` (this will run on staged files).
* If you've made changes to the frontend, you should run `cd frontend && npm run lint:fix && npm run build ; cd ..`
* If you've made changes to the VSCode extension, you should run `cd openhands/integrations/vscode && npm run lint:fix && npm run compile ; cd ../../..`
The pre-commit hooks MUST pass successfully before pushing any changes to the repository. This is a mandatory requirement to maintain code quality and consistency.
@@ -29,6 +30,12 @@ then re-run the command to ensure it passes. Common issues include:
- Trailing whitespace
- Missing newlines at end of files
## Git Best Practices
- Prefer specific `git add <filename>` instead of `git add .` to avoid accidentally staging unintended files
- Be especially careful with `git reset --hard` after staging files, as it will remove accidentally staged files
- When remote has new changes, use `git fetch upstream && git rebase upstream/<branch>` on the same branch
## Repository Structure
Backend:
- Located in the `openhands` directory
@@ -60,6 +67,22 @@ Frontend:
- Mutation hooks should follow the pattern use[Action] (e.g., `useDeleteConversation`)
- Architecture rule: UI components → TanStack Query hooks → Data Access Layer (`frontend/src/api`) → API endpoints
VSCode Extension:
- Located in the `openhands/integrations/vscode` directory
- Setup: Run `npm install` in the extension directory
- Linting:
- Run linting with fixes: `npm run lint:fix`
- Check only: `npm run lint`
- Type checking: `npm run typecheck`
- Building:
- Compile TypeScript: `npm run compile`
- Package extension: `npm run package-vsix`
- Testing:
- Run tests: `npm run test`
- Development Best Practices:
- Use `vscode.window.createOutputChannel()` for debug logging instead of `showErrorMessage()` popups
- Pre-commit process runs both frontend and backend checks when committing extension changes
## Template for Github Pull Request
If you are starting a pull request (PR), please follow the template in `.github/pull_request_template.md`.
@@ -68,6 +91,29 @@ If you are starting a pull request (PR), please follow the template in `.github/
These details may or may not be useful for your current task.
### Microagents
Microagents are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They are Markdown files that can include frontmatter for configuration.
#### Types:
- **Public Microagents**: Located in `microagents/`, available to all users
- **Repository Microagents**: Located in `.openhands/microagents/`, specific to this repository
#### Loading Behavior:
- **Without frontmatter**: Always loaded into LLM context
- **With triggers in frontmatter**: Only loaded when user's message matches the specified trigger keywords
#### Structure:
```yaml
---
triggers:
- keyword1
- keyword2
---
# Microagent Content
Your specialized knowledge and instructions here...
```
### Frontend
#### Action Handling:
@@ -95,3 +141,65 @@ These details may or may not be useful for your current task.
2. Add the setting to the backend:
- Add the setting to the `Settings` model in `openhands/storage/data_models/settings.py`
- Update any relevant backend code to apply the setting (e.g., in session creation)
### Adding New LLM Models
To add a new LLM model to OpenHands, you need to update multiple files across both frontend and backend:
#### Model Configuration Procedure:
1.**Frontend Model Arrays** (`frontend/src/utils/verified-models.ts`):
- Add the model to `VERIFIED_MODELS` array (main list of all verified models)
- Add to provider-specific arrays based on the model's provider:
-`VERIFIED_OPENAI_MODELS` for OpenAI models
-`VERIFIED_ANTHROPIC_MODELS` for Anthropic models
-`VERIFIED_MISTRAL_MODELS` for Mistral models
-`VERIFIED_OPENHANDS_MODELS` for models available through OpenHands provider
@@ -52,50 +52,75 @@ which comes with $20 in free credits for new users.
## 💻 Running OpenHands Locally
OpenHands can also run on your local system using Docker.
See the [Running OpenHands](https://docs.all-hands.dev/usage/installation) guide for
system requirements and more information.
### Option 1: CLI Launcher (Recommended)
> [!WARNING]
> On a public network? See our [Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)
> to secure your deployment by restricting network binding and implementing additional security measures.
The easiest way to run OpenHands locally is using the CLI launcher with [uv](https://docs.astral.sh/uv/). This provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers.
**Install uv** (if you haven't already):
See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)!
> [!WARNING]
> On a public network? See our [Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)
> to secure your deployment by restricting network binding and implementing additional security measures.
### Getting Started
When you open the application, you'll be asked to choose an LLM provider and add an API key.
[Anthropic's Claude Sonnet 4](https://www.anthropic.com/api) (`anthropic/claude-sonnet-4-20250514`)
works best, but you have [many options](https://docs.all-hands.dev/usage/llms).
See the [Running OpenHands](https://docs.all-hands.dev/usage/installation) guide for
system requirements and more information.
## 💡 Other ways to run OpenHands
> [!CAUTION]
> [!WARNING]
> OpenHands is meant to be run by a single user on their local workstation.
> It is not appropriate for multi-tenant deployments where multiple users share the same instance. There is no built-in authentication, isolation, or scalability.
>
> If you're interested in running OpenHands in a multi-tenant environment, please
> [get in touch with us](https://docs.google.com/forms/d/e/1FAIpQLSet3VbGaz8z32gW9Wm-Grl4jpt5WgMXPgJ4EDPVmCETCBpJtQ/viewform)
> for advanced deployment options.
> If you're interested in running OpenHands in a multi-tenant environment, check out the source-available, commercially-licensed
You can also [connect OpenHands to your local filesystem](https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem),
run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/usage/how-to/headless-mode),
You can [connect OpenHands to your local filesystem](https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem),
interact with it via a [friendly CLI](https://docs.all-hands.dev/usage/how-to/cli-mode),
run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/usage/how-to/headless-mode),
or run it on tagged issues with [a github action](https://docs.all-hands.dev/usage/how-to/github-action).
Visit [Running OpenHands](https://docs.all-hands.dev/usage/installation) for more information and setup instructions.
@@ -118,7 +143,7 @@ troubleshooting resources, and advanced configuration options.
OpenHands is a community-driven project, and we welcome contributions from everyone. We do most of our communication
through Slack, so this is the best place to start, but we also are happy to have you contact us on Discord or Github:
- [Join our Slack workspace](https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A) - Here we talk about research, architecture, and future development.
- [Join our Slack workspace](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA) - Here we talk about research, architecture, and future development.
- [Join our Discord server](https://discord.gg/ESHStjSjD4) - This is a community-run server for general discussion, questions, and feedback.
- [Read or post Github Issues](https://github.com/All-Hands-AI/OpenHands/issues) - Check out the issues we're working on, or add your own ideas.
#- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234} # enable this only if you want a specific non-root sandbox user but you will have to manually adjust permissions of ~/.openhands for this user
description: This guide walks you through the process of installing OpenHands Cloud for your Bitbucket repositories. Once
set up, it will allow OpenHands to work with your Bitbucket repository.
---
## Prerequisites
- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/usage/cloud/openhands-cloud).
## IP Whitelisting
If your Bitbucket Cloud instance has IP restrictions, you'll need to whitelist the following IP addresses to allow OpenHands to access your repositories:
### Core App IP
```
34.68.58.200
```
### Runtime IPs
```
34.10.175.217
34.136.162.246
34.45.0.142
34.28.69.126
35.224.240.213
34.70.174.52
34.42.4.87
35.222.133.153
34.29.175.97
34.60.55.59
```
## Adding Bitbucket Repository Access
Upon signing into OpenHands Cloud with a Bitbucket account, OpenHands will have access to your repositories.
## Working With Bitbucket Repos in Openhands Cloud
After signing in with a Bitbucket account, use the `select a repo` and `select a branch` dropdowns to select the
appropriate repository and branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
@@ -51,8 +51,7 @@ Giving GitHub repository access to OpenHands also allows you to work on GitHub i
### Working with Issues
On your repository, label an issue with `openhands` or add a message starting with
`@openhands`. OpenHands will:
On your repository, label an issue with `openhands` or add a message starting with `@openhands`. OpenHands will:
1. Comment on the issue to let you know it is working on it.
- You can click on the link to track the progress on OpenHands Cloud.
2. Open a pull request if it determines that the issue has been successfully resolved.
@@ -65,6 +64,8 @@ To get OpenHands to work on pull requests, mention `@openhands` in the comments
- Request updates
- Get code explanations
**Important Note**: The `@openhands` mention functionality in pull requests only works if the pull request is both *to* and *from* a repository that you have added through the interface. This is because OpenHands needs appropriate permissions to access both repositories.
## Next Steps
- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
@@ -25,6 +25,33 @@ OpenHands requests an API-scoped token during OAuth authentication. By default,
To restrict the agent's permissions, you can define a custom secret `GITLAB_TOKEN`, which will override the default token assigned to the agent.
While the high-permission API token is still requested and used for other components of the application (e.g. opening merge requests), the agent will not have access to it.
## Working on GitLab Issues and Merge Requests Using Openhands
<Note>
This feature works for personal projects and is available for group projects with a
[Premium or Ultimate tier subscription](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks).
A webhook is automatically installed within a few minutes after the owner/maintainer of the project or group logs into
OpenHands Cloud. If you decide to delete the webhook, then re-installing will require the support of All Hands AI but we are planning to improve this in a future release.
</Note>
Giving GitLab repository access to OpenHands also allows you to work on GitLab issues and merge requests directly.
### Working with Issues
On your repository, label an issue with `openhands` or add a message starting with `@openhands`. OpenHands will:
1. Comment on the issue to let you know it is working on it.
- You can click on the link to track the progress on OpenHands Cloud.
2. Open a merge request if it determines that the issue has been successfully resolved.
3. Comment on the issue with a summary of the performed tasks and a link to the PR.
### Working with Merge Requests
To get OpenHands to work on merge requests, mention `@openhands` in the comments to:
- Ask questions
- Request updates
- Get code explanations
## Next Steps
- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
description: Complete guide for setting up Jira Data Center integration with OpenHands Cloud, including service account creation, personal access token generation, webhook configuration, and workspace integration setup.
---
# Jira Data Center Integration
## Platform Configuration
### Step 1: Create Service Account
1. **Access User Management**
- Log in to Jira Data Center as administrator
- Go to **Administration** > **User Management**
2. **Create User**
- Click **Create User**
- Username: `openhands-agent`
- Full Name: `OpenHands Agent`
- Email: `openhands@yourcompany.com` (replace with your preferred service account email)
- Password: Set a secure password
- Click **Create**
3. **Assign Permissions**
- Add user to appropriate groups
- Ensure access to relevant projects
- Grant necessary project permissions
### Step 2: Generate API Token
1. **Personal Access Tokens**
- Log in as the service account
- Go to **Profile** > **Personal Access Tokens**
- Click **Create token**
- Name: `OpenHands Cloud Integration`
- Expiry: Set appropriate expiration (recommend 1 year)
- Click **Create**
- **Important**: Copy and store the token securely
### Step 3: Configure Webhook
1. **Create Webhook**
- Go to **Administration** > **System** > **WebHooks**
- **JQL Filter**: Leave empty (or customize as needed)
- Click **Create**
- **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
---
## Workspace Integration
### Step 1: Log in to OpenHands Cloud
1. **Navigate and Authenticate**
- Go to [OpenHands Cloud](https://app.all-hands.dev/)
- Sign in with your Git provider (GitHub, GitLab, or BitBucket)
- **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
### Step 2: Configure Jira Data Center Integration
1. **Access Integration Settings**
- Navigate to **Settings** > **Integrations**
- Locate **Jira Data Center** section
2. **Configure Workspace**
- Click **Configure** button
- Enter your workspace name and click **Connect**
- If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
- **Webhook Secret**: The webhook secret from Step 3 above
- **Service Account Email**: The service account email from Step 1 above
- **Service Account API Key**: The personal access token from Step 2 above
- Ensure **Active** toggle is enabled
<Note>
Workspace name is the host name of your Jira Data Center instance.
Here the workspace name is **jira.all-hands.dev**.
</Note>
3. **Complete OAuth Flow**
- You'll be redirected to Jira Data Center to complete OAuth verification
- Grant the necessary permissions to verify your workspace access. If you have access to multiple workspaces, select the correct one that you initially provided
- If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
### Managing Your Integration
**Edit Configuration:**
- Click the **Edit** button next to your configured platform
- Update any necessary credentials or settings
- Click **Update** to apply changes
- You will need to repeat the OAuth flow as before
- **Important:** Only the original user who created the integration can see the edit view
**Unlink Workspace:**
- In the edit view, click **Unlink** next to the workspace name
- This will deactivate your workspace link
- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
description: Complete guide for setting up Jira Cloud integration with OpenHands Cloud, including service account creation, API token generation, webhook configuration, and workspace integration setup.
---
# Jira Cloud Integration
## Platform Configuration
### Step 1: Create Service Account
1. **Navigate to User Management**
- Go to [Atlassian Admin](https://admin.atlassian.com/)
- Select your organization
- Go to **Directory** > **Users**
2. **Create OpenHands Service Account**
- Click **Service accounts**
- Click **Create a service account**
- Name: `OpenHands Agent`
- Click **Next**
- Select **User** role for Jira app
- Click **Create**
### Step 2: Generate API Token
1. **Access Service Account Configuration**
- Locate the created service account from above step and click on it
- Click **Create API token**
- Set the expiry to 365 days (maximum allowed value)
- Click **Next**
- In **Select token scopes** screen, filter by following values
- App: Jira
- Scope type: Classic
- Scope actions: Write, Read
- Select `read:jira-work` and `write:jira-work` scopes
- Click **Next**
- Review and create API token
- **Important**: Copy and securely store the token immediately
### Step 3: Configure Webhook
1. **Navigate to Webhook Settings**
- Go to **Jira Settings** > **System** > **WebHooks**
- **JQL Filter**: Leave empty (or customize as needed)
- Click **Create**
- **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
---
## Workspace Integration
### Step 1: Log in to OpenHands Cloud
1. **Navigate and Authenticate**
- Go to [OpenHands Cloud](https://app.all-hands.dev/)
- Sign in with your Git provider (GitHub, GitLab, or BitBucket)
- **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
### Step 2: Configure Jira Integration
1. **Access Integration Settings**
- Navigate to **Settings** > **Integrations**
- Locate **Jira Cloud** section
2. **Configure Workspace**
- Click **Configure** button
- Enter your workspace name and click **Connect**
- **Important:** Make sure you enter the full workspace name, eg: **yourcompany.atlassian.net**
- If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
- **Webhook Secret**: The webhook secret from Step 3 above
- **Service Account Email**: The service account email from Step 1 above
- **Service Account API Key**: The API token from Step 2 above
- Ensure **Active** toggle is enabled
<Note>
Workspace name is the host name when accessing a resource in Jira Cloud.
Eg: https://all-hands.atlassian.net/browse/OH-55
Here the workspace name is **all-hands**.
</Note>
3. **Complete OAuth Flow**
- You'll be redirected to Jira Cloud to complete OAuth verification
- Grant the necessary permissions to verify your workspace access.
- If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
### Managing Your Integration
**Edit Configuration:**
- Click the **Edit** button next to your configured platform
- Update any necessary credentials or settings
- Click **Update** to apply changes
- You will need to repeat the OAuth flow as before
- **Important:** Only the original user who created the integration can see the edit view
**Unlink Workspace:**
- In the edit view, click **Unlink** next to the workspace name
- This will deactivate your workspace link
- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that workspace integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
description: Complete guide for setting up Linear integration with OpenHands Cloud, including service account creation, API key generation, webhook configuration, and workspace integration setup.
---
# Linear Integration
## Platform Configuration
### Step 1: Create Service Account
1. **Access Team Settings**
- Log in to Linear as a team admin
- Go to **Settings** > **Members**
2. **Invite Service Account**
- Click **Invite members**
- Email: `openhands@yourcompany.com` (replace with your preferred service account email)
- Role: **Member** (with appropriate team access)
- Send invitation
3. **Complete Setup**
- Accept invitation from the service account email
- Complete profile setup
- Ensure access to relevant teams/workspaces
### Step 2: Generate API Key
1. **Access API Settings**
- Log in as the service account
- Go to **Settings** > **Security & access**
2. **Create Personal API Key**
- Click **Create new key**
- Name: `OpenHands Cloud Integration`
- Scopes: Select the following:
- `Read` - Read access to issues and comments
- `Create comments` - Ability to create or update comments
- Select the teams you want to provide access to, or allow access for all teams you have permissions for
- Click **Create**
- **Important**: Copy and store the API key securely
- Select the teams you want to provide access to, or allow access for all public teams
- Click **Create webhook**
- **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
---
## Workspace Integration
### Step 1: Log in to OpenHands Cloud
1. **Navigate and Authenticate**
- Go to [OpenHands Cloud](https://app.all-hands.dev/)
- Sign in with your Git provider (GitHub, GitLab, or BitBucket)
- **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
### Step 2: Configure Linear Integration
1. **Access Integration Settings**
- Navigate to **Settings** > **Integrations**
- Locate **Linear** section
2. **Configure Workspace**
- Click **Configure** button
- Enter your workspace name and click **Connect**
- If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
- **Webhook Secret**: The webhook secret from Step 3 above
- **Service Account Email**: The service account email from Step 1 above
- **Service Account API Key**: The API key from Step 2 above
- Ensure **Active** toggle is enabled
<Note>
Workspace name is the identifier after the host name when accessing a resource in Linear.
Eg: https://linear.app/allhands/issue/OH-37
Here the workspace name is **allhands**.
</Note>
3. **Complete OAuth Flow**
- You'll be redirected to Linear to complete OAuth verification
- Grant the necessary permissions to verify your workspace access. If you have access to multiple workspaces, select the correct one that you initially provided
- If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
### Managing Your Integration
**Edit Configuration:**
- Click the **Edit** button next to your configured platform
- Update any necessary credentials or settings
- Click **Update** to apply changes
- You will need to repeat the OAuth flow as before
- **Important:** Only the original user who created the integration can see the edit view
**Unlink Workspace:**
- In the edit view, click **Unlink** next to the workspace name
- This will deactivate your workspace link
- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
description: Overview of OpenHands Cloud integrations with project management platforms including Jira Cloud, Jira Data Center, and Linear. Learn about setup requirements, usage methods, and troubleshooting.
---
# Project Management Tool Integrations
## Overview
OpenHands Cloud integrates with project management platforms (Jira Cloud, Jira Data Center, and Linear) to enable AI-powered task delegation. Users can invoke the OpenHands agent by:
- Adding `@openhands` in ticket comments
- Adding the `openhands` label to tickets
## Prerequisites
Integration requires two levels of setup:
1. **Platform Configuration** - Administrative setup of service accounts and webhooks on your project management platform (see individual platform documentation below)
2. **Workspace Integration** - Self-service configuration through the OpenHands Cloud UI to link your OpenHands account to the target workspace
### Platform-Specific Setup Guides:
- [Jira Cloud Integration](./jira-integration.md)
- [Jira Data Center Integration](./jira-dc-integration.md)
- [Linear Integration](./linear-integration.md)
## Usage
Once both the platform configuration and workspace integration are completed, users can trigger the OpenHands agent within their project management platforms using two methods:
### Method 1: Comment Mention
Add a comment to any issue with `@openhands` followed by your task description:
```
@openhands Please implement the user authentication feature described in this ticket
```
### Method 2: Label-based Delegation
Add the label `openhands` to any issue. The OpenHands agent will automatically process the issue based on its description and requirements.
### Git Repository Detection
The OpenHands agent needs to identify which Git repository to work with when processing your issues. Here's how to ensure proper repository detection:
#### Specifying the Target Repository
**Required:** Include the target Git repository in your issue description or comment to ensure the agent works with the correct codebase.
**Supported Repository Formats:**
- Full HTTPS URL: `https://github.com/owner/repository.git`
- GitHub URL without .git: `https://github.com/owner/repository`
- Owner/repository format: `owner/repository`
#### Platform-Specific Behavior
**Linear Integration:** When GitHub integration is enabled for your Linear workspace with issue sync activated, the target repository is automatically detected from the linked GitHub issue. Manual specification is not required in this configuration.
**Jira Integrations:** Always include the repository information in your issue description or `@openhands` comment to ensure proper repository detection.
## Troubleshooting
### Platform Configuration Issues
- **Webhook not triggering**: Verify the webhook URL is correct and the proper event types are selected (Comment, Issue updated)
- **API authentication failing**: Check API key/token validity and ensure required scopes are granted. If your current API token is expired, make sure to update it in the respective integration settings
- **Permission errors**: Ensure the service account has access to relevant projects/teams and appropriate permissions
### Workspace Integration Issues
- **Workspace linking requests credentials**: If there are no active workspace integrations for the workspace you specified, you need to configure it first. Contact your platform administrator that you want to integrate with (eg: Jira, Linear)
- **Integration not found**: Verify the workspace name matches exactly and that platform configuration was completed first
- **OAuth flow fails**: Make sure that you're authorizing with the correct account with proper workspace access
### General Issues
- **Agent not responding**: Check webhook logs in your platform settings and verify service account status
- **Agent fails to identify git repo**: Ensure you're signing in with the same Git provider account that contains the repositories you want OpenHands to work on
- **Partial functionality**: Ensure both platform configuration and workspace integration are properly completed
### Getting Help
For additional support, contact OpenHands Cloud support with:
- Your integration platform (Linear, Jira Cloud, or Jira Data Center)
- Workspace name
- Error logs from webhook/integration attempts
- Screenshots of configuration settings (without sensitive credentials)
OpenHands utilizes a large language model (LLM), which may generate responses that are inaccurate or incomplete. While we strive for accuracy, OpenHands' outputs are not guaranteed to be correct, and we encourage users to validate critical information independently.
</Info>
## Prerequisites
- Access to OpenHands Cloud.
@@ -15,7 +28,7 @@ description: This guide walks you through installing the OpenHands Slack app.
**This step is for Slack admins/owners**
1. Make sure you have permissions to install Apps to your workspace.
2. Click the button below to install OpenHands Slack App <a target="_blank" href="https://slack.com/oauth/v2/authorize?client_id=7477886716822.8729519890534&scope=app_mentions:read,chat:write,users:read,channels:history,groups:history,mpim:history,im:history&user_scope=channels:history,groups:history,im:history,mpim:history"><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcSet="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x" /></a>
2. Click the button below to install OpenHands Slack App <a target="_blank" href="https://slack.com/oauth/v2/authorize?client_id=7477886716822.8729519890534&scope=app_mentions:read,channels:history,chat:write,groups:history,im:history,mpim:history,users:read&user_scope="><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcSet="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x" /></a>
3. In the top right corner, select the workspace to install the OpenHands Slack app.
description: This page outlines all available configuration options for OpenHands, allowing you to customize its behavior and integrate it with other services. In GUI Mode, any settings applied through the Settings UI will take precedence.
description: This page outlines all available configuration options for OpenHands, allowing you to customize its
behavior and integrate it with other services.
---
<Note>
In GUI Mode, any settings applied through the Settings UI will take precedence.
</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.
**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported)
**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported) and `uv` for the default `fetch` MCP server (more details below).
1. Install OpenHands using pip:
#### Recommended: Using uv
```bash
pip install openhands-ai
```
We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands experience. uv provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers.
Or if you prefer not to manage your own Python environment, you can use `uvx`:
1. **Install uv** (if you haven't already):
See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
2. **Launch OpenHands CLI**:
```bash
uvx --python 3.12 --from openhands-ai openhands
```
2. Launch an interactive OpenHands conversation from the command line:
<AccordionGroup>
<Accordion title="Alternative: Traditional pip installation">
If you prefer to use pip:
```bash
openhands
# Install OpenHands
pip install openhands-ai
```
3. Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
Note that you'll still need `uv` installed for the default MCP servers to work properly.
</Accordion>
<Accordion title="Create shell aliases for easy access across environments">
Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.):
```bash
# Add OpenHands aliases (recommended)
alias openhands="uvx --python 3.12 --from openhands-ai openhands"
alias oh="uvx --python 3.12 --from openhands-ai openhands"
```
After adding these lines, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell).
</Accordion>
<Accordion title="Install OpenHands in home directory without global installation">
You can install OpenHands in a virtual environment in your home directory using `uv`:
```bash
# Create a virtual environment in your home directory
> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
<Note>
If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your
conversation history to the new location.
</Note>
This launches the CLI in Docker, allowing you to interact with OpenHands as described above.
This launches the CLI in Docker, allowing you to interact with OpenHands.
The `-e SANDBOX_USER_ID=$(id -u)` ensures files created by the agent in your workspace have the correct permissions.
The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
permissions. This prevents the agent from creating root-owned files in the mounted workspace.
The conversation history will be saved in `~/.openhands/sessions`.
## Interactive CLI Overview
@@ -99,6 +169,7 @@ You can use the following commands whenever the prompt (`>`) is displayed:
| `/new` | Start a new conversation |
| `/settings` | View and modify current LLM/agent settings |
| `/resume` | Resume the agent if paused |
| `/mcp` | Manage MCP server configuration and view connection errors |
#### Settings and Configuration
@@ -108,7 +179,7 @@ follow the prompts:
- **Basic settings**: Choose a model/provider and enter your API key.
- **Advanced settings**: Set custom endpoints, enable or disable confirmation mode, and configure memory condensation.
Settings can also be managed via the `config.toml` file.
Settings can also be managed via the `config.toml` file in the current directory or `~/.openhands/config.toml`.
#### Repository Initialization
@@ -120,6 +191,41 @@ project details and structure. Use this when onboarding the agent to a new codeb
You can pause the agent while it is running by pressing `Ctrl-P`. To continue the conversation after pausing, simply
type `/resume` at the prompt.
#### MCP Server Management
To configure Model Context Protocol (MCP) servers, you can refer to the documentation on [MCP servers](../mcp) and use the `/mcp` command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
- **List configured servers**: View all currently configured MCP servers (SSE, Stdio, and SHTTP)
- **Add new server**: Interactively add a new MCP server with guided prompts
- **Remove server**: Remove an existing MCP server from your configuration
- **View errors**: Display any connection errors that occurred during MCP server startup
This command modifies your `~/.openhands/config.toml` file and will prompt you to restart OpenHands for changes to take effect.
By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands. You can also [enable search engine](../search-engine-setup) via the [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) by setting the `search_api_key` under the `[core]` section in the `~/.openhands/config.toml` file.
##### Example of the `config.toml` file with MCP server configuration:
description: This guide is for users that would like to use their own custom Docker image for the runtime. For example, with certain tools or programming languages pre-installed.
description: This guide is for users that would like to use their own custom Docker image for the runtime.
For example, with certain tools or programming languages pre-installed.
---
The sandbox is where the agent performs its tasks. Instead of running commands directly on your computer
@@ -7,6 +7,67 @@ description: High level overview of the Graphical User Interface (GUI) in OpenHa
- [OpenHands is running](/usage/local-setup)
## Launching the GUI Server
### Using the CLI Command
You can launch the OpenHands GUI server directly from the command line using the `serve` command:
<Callout type="info">
**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/how-to/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
</Callout>
```bash
openhands serve
```
This command will:
- Check that Docker is installed and running
- Pull the required Docker images
- Launch the OpenHands GUI server at http://localhost:3000
- Use the same configuration directory (`~/.openhands`) as the CLI mode
#### Mounting Your Current Directory
To mount your current working directory into the GUI server container, use the `--mount-cwd` flag:
```bash
openhands serve --mount-cwd
```
This is useful when you want to work on files in your current directory through the GUI. The directory will be mounted at `/workspace` inside the container.
#### Using GPU Support
If you have NVIDIA GPUs and want to make them available to the OpenHands container, use the `--gpu` flag:
```bash
openhands serve --gpu
```
This will enable GPU support via nvidia-docker, mounting all available GPUs into the container. You can combine this with other flags:
```bash
openhands serve --gpu --mount-cwd
```
**Prerequisites for GPU support:**
- NVIDIA GPU drivers must be installed on your host system
- [NVIDIA Container Toolkit (nvidia-docker2)](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) must be installed and configured
#### Requirements
Before using the `openhands serve` command, ensure that:
- Docker is installed and running on your system
- You have internet access to pull the required Docker images
- Port 3000 is available on your system
The CLI will automatically check these requirements and provide helpful error messages if anything is missing.
### Using Docker Directly
Alternatively, you can run the GUI server using Docker directly. See the [local setup guide](/usage/local-setup) for detailed Docker instructions.
## Overview
### Initial Setup
@@ -25,7 +86,8 @@ You can use the Settings page at any time to:
- Setup the LLM provider and model for OpenHands.
- [Setup the search engine](/usage/search-engine-setup).
- [Configure MCP servers](/usage/mcp).
- [Connect to GitHub](/usage/how-to/gui-mode#github-setup) and [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup).
- [Connect to GitHub](/usage/how-to/gui-mode#github-setup), [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup)
and [connect to Bitbucket](/usage/how-to/gui-mode#bitbucket-setup).
- Set application settings like your preferred language, notifications and other preferences.
@@ -18,42 +18,79 @@ poetry run python -m openhands.core.main -t "write a bash script that prints hi"
You'll need to be sure to set your model, API key, and other settings via environment variables
[or the `config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml).
## With Docker
### Working with Repositories
To run OpenHands in Headless mode with Docker:
You can specify a repository for OpenHands to work with using `--selected-repo` or the `SANDBOX_SELECTED_REPO` environment variable:
1. Set the following environment variables in your terminal:
- `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](../runtimes/docker#using-sandbox_volumes))
- `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"`)
- `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
2. Run the following Docker command:
> **Note**: Currently, authentication tokens (GITHUB_TOKEN, GITLAB_TOKEN, or BITBUCKET_TOKEN) are required for all repository operations, including public repositories. This is a known limitation that may be addressed in future versions to allow tokenless access to public repositories.
```bash
# Using command-line argument
poetry run python -m openhands.core.main \
--selected-repo "owner/repo-name" \
-t "analyze the codebase and suggest improvements"
# Using environment variable
export SANDBOX_SELECTED_REPO="owner/repo-name"
poetry run python -m openhands.core.main -t "fix any linting issues"
# Authentication tokens are currently required for ALL repository operations (public and private)
# This includes GitHub, GitLab, and Bitbucket repositories
export GITHUB_TOKEN="your-token" # or GITLAB_TOKEN, BITBUCKET_TOKEN
poetry run python -m openhands.core.main \
--selected-repo "owner/repo-name" \
-t "review the security implementation"
# Using task files instead of inline task
echo "Review the README and suggest improvements" > task.txt
poetry run python -m openhands.core.main -f task.txt --selected-repo "owner/repo"
```
## With Docker
Set environment variables and run the Docker command:
```bash
# Set required environment variables
export SANDBOX_VOLUMES="/path/to/workspace" # See SANDBOX_VOLUMES docs for details
python -m openhands.core.main -t "write a bash script that prints hi"
```
> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
> **Note**: If you used OpenHands before version 0.44, run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history.
The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
permissions. This prevents the agent from creating root-owned files in the mounted workspace.
## Advanced Headless Configurations
## Additional Options
To view all available configuration options for headless mode, run the Python command with the `--help` flag.
Common command-line options:
- `-d "/path/to/workspace"` - Set working directory
- `-f task.txt` - Load task from file
- `-i 50` - Set max iterations
- `-b 10.0` - Set budget limit (USD)
- `--no-auto-continue` - Interactive mode
### Additional Logs
Run `poetry run python -m openhands.core.main --help` for all options.
For the headless mode to log all the agent actions, in the terminal run: `export LOG_ALL_EVENTS=true`
Set `export LOG_ALL_EVENTS=true` to log all agent actions.
@@ -10,16 +10,18 @@ This section is for users who want to connect OpenHands to different LLMs.
## Model Recommendations
Based on our evaluations of language models for coding tasks (using the SWE-bench dataset), we can provide some
recommendations for model selection. Our latest benchmarking results can be found in [this spreadsheet](https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=0).
recommendations for model selection. Our latest benchmarking results can be found in
If you have successfully run OpenHands with specific providers, we encourage you to open a PR to share your setup process
to help others using the same provider!
@@ -37,6 +39,12 @@ limits and monitor usage.
- [mistralai/devstral-small](https://www.all-hands.dev/blog/devstral-a-new-state-of-the-art-open-model-for-coding-agents) (20 May 2025) -- also available through [OpenRouter](https://openrouter.ai/mistralai/devstral-small:free)
- [all-hands/openhands-lm-32b-v0.1](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model) (31 March 2025) -- also available through [OpenRouter](https://openrouter.ai/all-hands/openhands-lm-32b-v0.1)
### Known Issues
<Warning>
As of July 2025, there are known issues with Gemini 2.5 Pro conversations taking longer than normal with OpenHands. We are continuing to investigate.
</Warning>
<Note>
Most current local and open source models are not as powerful. When using such models, you may see long
wait times between messages, poor responses, or errors about malformed JSON. OpenHands can only be as powerful as the
@@ -70,9 +78,21 @@ We have a few guides for running OpenHands with specific model providers:
- [Groq](/usage/llms/groq)
- [Local LLMs with SGLang or vLLM](/usage/llms/local-llms)
- [LiteLLM Proxy](/usage/llms/litellm-proxy)
- [Moonshot AI](/usage/llms/moonshot)
- [OpenAI](/usage/llms/openai-llms)
- [OpenHands](/usage/llms/openhands-llms)
- [OpenRouter](/usage/llms/openrouter)
## Model Customization
LLM providers have specific settings that can be customized to optimize their performance with OpenHands, such as:
- **Custom Tokenizers**: For specialized models, you can add a suitable tokenizer.
Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.45
Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.53
Starting OpenHands...
Running OpenHands as root
14:22:13 - openhands:INFO: server_config.py:50 - Using config class None
@@ -119,7 +119,7 @@ When started for the first time, OpenHands will prompt you to set up the LLM pro
That's it! You can now start using OpenHands with the local LLM server.
If you encounter any issues, let us know on [Slack](https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A) or [Discord](https://discord.gg/ESHStjSjD4).
If you encounter any issues, let us know on [Slack](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA) or [Discord](https://discord.gg/ESHStjSjD4).
description: How to use Moonshot AI models with OpenHands
---
## Using Moonshot AI with OpenHands
[Moonshot AI](https://platform.moonshot.ai/) offers several powerful models, including Kimi-K2, which has been verified to work well with OpenHands.
### Setup
1. Sign up for an account at [Moonshot AI Platform](https://platform.moonshot.ai/)
2. Generate an API key from your account settings
3. Configure OpenHands to use Moonshot AI:
| Setting | Value |
| --- | --- |
| LLM Provider | `moonshot` |
| LLM Model | `kimi-k2-0711-preview` |
| API Key | Your Moonshot API key |
### Recommended Models
- `moonshot/kimi-k2-0711-preview` - Kimi-K2 is Moonshot's most powerful model with a 131K context window, function calling support, and web search capabilities.
description: OpenHands LLM provider with access to state-of-the-art (SOTA) agentic coding models.
---
## Obtain Your OpenHands LLM API Key
1. [Log in to OpenHands Cloud](/usage/cloud/openhands-cloud).
2. Go to the Settings page and navigate to the `API Keys` tab.
3. Copy your `LLM API Key`.
## Configuration
When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
- `LLM Provider` to `OpenHands`
- `LLM Model` to the model you will be using (e.g. claude-sonnet-4-20250514)
- `API Key` to your OpenHands LLM API key copied from above
## Using OpenHands LLM Provider in the CLI
1. [Run OpenHands CLI](/usage/how-to/cli-mode).
2. To select OpenHands as the LLM provider:
- If this is your first time running the CLI, choose `openhands` and then select the model that you would like to use.
- If you have previously run the CLI, run the `/settings` command and select to modify the `Basic` settings. Then
choose `openhands` and finally the model.
## Pricing
Pricing follows official API provider rates. [You can view model prices here.](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json)
For `qwen3-coder-480b`, we charge the cheapest FP8 rate available on openrouter: \$0.4 per million input tokens and \$1.6 per million output tokens.
@@ -66,20 +66,64 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
### Start the App
#### Option 1: Using the CLI Launcher with uv (Recommended)
We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands experience. uv provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers (like the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)).
**Install uv** (if you haven't already):
See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
This will automatically handle Docker requirements checking, image pulling, and launching the GUI server. The `--gpu` flag enables GPU support via nvidia-docker, and `--mount-cwd` mounts your current directory into the container.
<Accordion title="Alternative: Traditional pip installation">
If you prefer to use pip and have Python 3.12+ installed:
```bash
# Install OpenHands
pip install openhands-ai
# Launch the GUI server
openhands serve
```
Note that you'll still need `uv` installed for the default MCP servers to work properly.
</Accordion>
#### Option 2: Using Docker Directly
<Accordion title="Docker Command (Click to expand)">
> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
You'll find OpenHands running at http://localhost:3000!
@@ -100,6 +144,16 @@ OpenHands requires an API key to access most language models. Here's how to get
<AccordionGroup>
<Accordion title="OpenHands (Recommended)">
1. [Log in to OpenHands Cloud](https://app.all-hands.dev).
2. Go to the Settings page and navigate to the `API Keys` tab.
3. Copy your `LLM API Key`.
OpenHands provides access to state-of-the-art agentic coding models with competitive pricing. [Learn more about OpenHands LLM provider](/usage/llms/openhands-llms).
</Accordion>
<Accordion title="Anthropic (Claude)">
1. [Create an Anthropic account](https://console.anthropic.com/).
description: This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you to extend the agent's capabilities with custom tools.
description: This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you
to extend the agent's capabilities with custom tools.
---
## Overview
@@ -9,38 +10,83 @@ Model Context Protocol (MCP) is a mechanism that allows OpenHands to communicate
servers can provide additional functionality to the agent, such as specialized data processing, external API access,
or custom tools. MCP is based on the open standard defined at [modelcontextprotocol.io](https://modelcontextprotocol.io).
<Note>
MCP is currently not available on OpenHands Cloud. This feature is only available when running OpenHands locally.
</Note>
### How MCP Works
When OpenHands starts, it:
1. Reads the MCP configuration.
2. Connects to any configured SSE and SHTTP servers.
3. Starts any configured stdio servers.
4. Registers the tools provided by these servers with the agent.
The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:
1. OpenHands routes the call to the appropriate MCP server.
2. The server processes the request and returns a response.
3. OpenHands converts the response to an observation and presents it to the agent.
## Configuration
MCP configuration can be defined in:
* The OpenHands UI through the Settings under the `MCP` tab.
* The `config.toml` file under the `[mcp]` section if not using the UI.
### Configuration Example via config.toml
### Configuration Examples
#### Recommended: Using Proxy Servers (SSE/HTTP)
For stdio-based MCP servers, we recommend using MCP proxy tools like [`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
[SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to HTTP/SSE endpoints:
@@ -56,8 +102,26 @@ SSE servers are configured using either a string URL or an object with the follo
- Type: `str`
- Description: The URL of the SSE server
- `api_key` (optional)
- Type: `str`
- Description: API key for authentication
### SHTTP Servers
SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
- `url` (required)
- Type: `str`
- Description: The URL of the SHTTP server
- `api_key` (optional)
- Type: `str`
- Description: API key for authentication
### Stdio Servers
**Note**: While stdio servers are supported, we recommend using MCP proxies (see above) for better reliability and performance.
Stdio servers are configured using an object with the following properties:
- `name` (required)
@@ -78,17 +142,55 @@ Stdio servers are configured using an object with the following properties:
- Default: `{}`
- Description: Environment variables to set for the server process
## How MCP Works
When OpenHands starts, it:
#### When to Use Direct Stdio
1. Reads the MCP configuration.
2. Connects to any configured SSE servers.
3. Starts any configured stdio servers.
4. Registers the tools provided by these servers with the agent.
Direct stdio connections may still be appropriate in these scenarios:
- **Development and testing**: Quick prototyping of MCP servers
- **Simple, single-use tools**: Tools that don't require high reliability or concurrent access
- **Local-only environments**: When you don't want to manage additional proxy processes
The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:
For production use, we recommend using proxy tools like SuperGateway.
1. OpenHands routes the call to the appropriate MCP server.
2. The server processes the request and returns a response.
3. OpenHands converts the response to an observation and presents it to the agent.
### Other Proxy Tools
Other options include:
- **Custom FastAPI/Express servers**: Build your own HTTP wrapper around stdio MCP servers
- **Docker-based proxies**: Containerized solutions for better isolation
- **Cloud-hosted MCP services**: Third-party services that provide MCP endpoints
### Troubleshooting MCP Connections
#### Common Issues with Stdio Servers
- **Process crashes**: Stdio processes may crash without proper error handling
- **Deadlocks**: Stdio communication can deadlock under high load
- **Resource leaks**: Zombie processes if not properly managed
- **Debugging difficulty**: Hard to inspect stdio communication
#### Benefits of Using Proxies
- **HTTP status codes**: Clear error reporting via standard HTTP responses
- **Request logging**: Easy to log and monitor HTTP requests
- **Load balancing**: Can distribute requests across multiple server instances
- **Health checks**: HTTP endpoints can provide health status
- **CORS support**: Better integration with web-based tools
## Transport Protocols
OpenHands supports three different MCP transport protocols:
### Server-Sent Events (SSE)
SSE is a legacy HTTP-based transport that uses Server-Sent Events for server-to-client communication and HTTP POST requests for client-to-server communication. This transport is suitable for basic streaming scenarios but has limitations in session management and connection resumability.
### Streamable HTTP (SHTTP)
SHTTP is the modern HTTP-based transport protocol that provides enhanced features over SSE:
- **Improved Session Management**: Supports stateful sessions with session IDs for maintaining context across requests
- **Connection Resumability**: Can resume broken connections and replay missed messages using event IDs
- **Bidirectional Communication**: Uses HTTP POST for client-to-server and optional SSE streams for server-to-client communication
- **Better Error Handling**: Enhanced error reporting and recovery mechanisms
SHTTP is the recommended transport for HTTP-based MCP servers as it provides better reliability and features compared to the legacy SSE transport.
### Standard Input/Output (stdio)
Stdio transport enables communication through standard input and output streams, making it ideal for local integrations and command-line tools. This transport is used for locally executed MCP servers that run as separate processes.
| `name` | The name of the microagent | No | Filename |
| `type` | The type of microagent (`repo`) | No | Inferred |
#### Repository Microagent Example
Here's an example of a repository microagent:
```yaml
---
# The type field is optional and will be inferred as 'repo' when no triggers are present
---
# Repository Guidelines
This repository follows these coding standards:
1. Use PEP 8 for Python code
2. Use ESLint for JavaScript code
3. Write unit tests for all new features
Keyword-triggered microagent file example located at `.openhands/microagents/yummy.md`:
```
This microagent is always active when working with the repository and provides repository-specific guidelines.
### MCP Tools Support
Microagents can also provide additional MCP (Model-Code-Prompt) tools to the agent. This is useful for extending the agent's capabilities with custom tools.
| `description` | A description of what the input should contain | Yes |
## Examples
### Standard Keyword Microagent Example
Standard keyword microagent file example located at `.openhands/microagents/yummy.md`:
```yaml
---
# The type field is optional and will be inferred as 'knowledge' when triggers are present
triggers:
- yummyhappy
- happyyummy
@@ -118,58 +33,4 @@ triggers:
The user has said the magic word. Respond with "That was delicious!"
```
### Command-Style Microagent Example
Command-style microagent file example located at `.openhands/microagents/fix_test.md`:
```yaml
---
# The type field is optional and will be inferred as 'task' when inputs are present
triggers:
- /fix_test
inputs:
- name: BRANCH_NAME
description: "Branch for the agent to work on"
- name: TEST_COMMAND_TO_RUN
description: "The test command you want the agent to work on. For example, `pytest tests/unit/test_bash_parsing.py`"
- name: FUNCTION_TO_FIX
description: "The name of function to fix"
- name: FILE_FOR_FUNCTION
description: "The path of the file that contains the function"
---
Can you check out branch "{{ BRANCH_NAME }}", and run {{ TEST_COMMAND_TO_RUN }}.
Help me fix these tests to pass by fixing the {{ FUNCTION_TO_FIX }} function in file {{ FILE_FOR_FUNCTION }}.
PLEASE DO NOT modify the tests by yourself -- Let me know if you think some of the tests are incorrect.
```
## Using Command-Style Microagents
Command-style microagents are designed to streamline common development tasks by providing structured templates for specific operations. They are triggered using a command-style format and will prompt the user for any required inputs.
### How to Use
1. Type `/` in the chat input to see available command-style microagents
2. Select a microagent from the dropdown or type its name (e.g., `/fix_test`)
3. The agent will prompt you for any required inputs
4. Provide the requested information
5. The agent will execute the task with your inputs
### Template Variables
In the body of a command-style microagent, you can reference input variables using the `{{ VARIABLE_NAME }}` syntax. These will be replaced with the user-provided values when the microagent is triggered.
### Available Command-Style Microagents
OpenHands includes several built-in command-style microagents:
| `/fix_test` | Fix failing tests by modifying a specific function |
| `/update_test` | Update tests for a new implementation |
| `/update_pr` | Update a pull request description |
| `/address_pr_comments` | Address comments on a pull request |
| `/add_repo_instruction` | Add instructions to the repository microagent |
[See examples of microagents in the official OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents)
[See examples of microagents triggered by keywords in the official OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents)
@@ -11,6 +11,8 @@ accordingly. However, they are applied to all repositories belonging to the orga
Add a `.openhands` repository under the organization or user and create a `microagents` directory and place the
microagents in that directory.
For GitLab organizations, use `openhands-config` as the repository name instead of `.openhands`, since GitLab doesn't support repository names starting with non-alphanumeric characters.
## Example
General microagent file example for organization `Great-Co` located inside the `.openhands` repository:
@@ -20,3 +22,14 @@ General microagent file example for organization `Great-Co` located inside the `
* Document interfaces and public APIs; use implementation comments only for non-obvious logic.
* Follow the same naming convention for variables, classes, constants, etc. already used in each repository.
```
For GitLab organizations, the same microagent would be located inside the `openhands-config` repository.
## User Microagents When Running Openhands on Your Own
<Note>
This works with CLI, headless and development modes. It does not work out of the box when running OpenHands using the docker command.
</Note>
When running OpenHands on your own, you can place microagents in the `~/.openhands/microagents` folder on your local
system and OpenHands will always load it for all your conversations.
@@ -8,7 +8,7 @@ description: Microagents are specialized prompts that enhance OpenHands with dom
Currently OpenHands supports the following types of microagents:
- [General Microagents](./microagents-repo): General guidelines for OpenHands about the repository.
- [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts, including command-style microagents that prompt for user inputs.
- [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts.
To customize OpenHands' behavior, create a .openhands/microagents/ directory in the root of your repository and
add `<microagent_name>.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](./microagents-repo) for details).
@@ -34,7 +34,7 @@ some-repository/
Each microagent file may include frontmatter that provides additional information. In some cases, this frontmatter
description: E2B is an open-source secure cloud environment (sandbox) made for running AI-generated code and agents.
---
[E2B](https://e2b.dev) offers [Python](https://pypi.org/project/e2b/) and [JS/TS](https://www.npmjs.com/package/e2b) SDK to spawn and control these sandboxes.
[E2B](https://e2b.dev) offers [Python](https://pypi.org/project/e2b/) and [JS/TS](https://www.npmjs.com/package/e2b)
SDK to spawn and control these sandboxes.
## Getting started
@@ -18,9 +19,13 @@ description: E2B is an open-source secure cloud environment (sandbox) made for r
Full CLI API is [here](https://e2b.dev/docs/cli/installation).
## OpenHands sandbox
You can use the E2B CLI to create a custom sandbox with a Dockerfile. Read the full guide [here](https://e2b.dev/docs/guide/custom-sandbox). The premade OpenHands sandbox for E2B is set up in the `containers` directory. and it's called `openhands`.
You can use the E2B CLI to create a custom sandbox with a Dockerfile. Read the full guide
[here](https://e2b.dev/docs/guide/custom-sandbox). The premade OpenHands sandbox for E2B is set up in the `containers`
directory. and it's called `openhands`.
## Debugging
You can connect to a running E2B sandbox with E2B CLI in your terminal.
- List all running sandboxes (based on your API key)
@@ -34,5 +39,6 @@ You can connect to a running E2B sandbox with E2B CLI in your terminal.
description: The Local Runtime allows the OpenHands agent to execute actions directly on your local machine without using Docker. This runtime is primarily intended for controlled environments like CI pipelines or testing scenarios where Docker is not available.
description: The Local Runtime allows the OpenHands agent to execute actions directly on your local machine without
using Docker. This runtime is primarily intended for controlled environments like CI pipelines or testing scenarios
- [Local Runtime](/usage/runtimes/local) - Direct execution on your local machine without Docker.
- And more third-party runtimes:
- [Modal Runtime](/usage/runtimes/modal) - Runtime provided by our partners at Modal.
- [Daytona Runtime](/usage/runtimes/daytona) - Runtime provided by Daytona.
### Third-Party Runtimes
The following third-party runtimes are available when you install the `third_party_runtimes` extra:
```bash
pip install openhands-ai[third_party_runtimes]
```
- [E2B Runtime](/usage/runtimes/e2b) - Open source runtime using E2B sandboxes.
- [Modal Runtime](/usage/runtimes/modal) - Serverless runtime using Modal infrastructure.
- [Runloop Runtime](/usage/runtimes/runloop) - Cloud runtime using Runloop infrastructure.
- [Daytona Runtime](/usage/runtimes/daytona) - Development environment runtime using Daytona.
**Note**: These third-party runtimes are supported by their respective developers, not by the OpenHands team. For issues specific to these runtimes, please refer to their documentation or contact their support teams.
description: This runtime is specifically designed for agent evaluation purposes only through the [OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be used to launch production OpenHands applications.
description: This runtime is specifically designed for agent evaluation purposes only through the
[OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be
used to launch production OpenHands applications.
---
OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details), it allows you to launch runtimes
in parallel in the cloud. Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to apply if you want to try this out!
OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details),
it allows you to launch runtimes in parallel in the cloud. Fill out
[this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to
description: Runloop provides a fast, secure and scalable AI sandbox (Devbox). Check out the [runloop docs](https://docs.runloop.ai/overview/what-is-runloop) for more detail.
description: Runloop provides a fast, secure and scalable AI sandbox (Devbox). Check out the
[runloop docs](https://docs.runloop.ai/overview/what-is-runloop) for more detail.
1. The agent can decide to search the web when it needs external information
2. Search queries are sent to Tavily's API via [Tavily's MCP server](https://github.com/tavily-ai/tavily-mcp) which includes a variety of [tools](https://docs.tavily.com/documentation/api-reference/introduction) (search, extract, crawl, map).
3. Results are returned and incorporated into the agent's context
4. The agent can use this information to provide more accurate and up-to-date responses
- The agent can decide to search the web when it needs external information.
- Search queries are sent to Tavily's API via [Tavily's MCP server](https://github.com/tavily-ai/tavily-mcp) which
includes a variety of [tools](https://docs.tavily.com/documentation/api-reference/introduction) (search, extract, crawl, map).
- Results are returned and incorporated into the agent's context.
- The agent can use this information to provide more accurate and up-to-date responses.
### Limitations
- Search results depend on Tavily's coverage and freshness
- Usage may be subject to Tavily's rate limits and pricing tiers
- The agent will only search when it determines that external information is needed
- Search results depend on Tavily's coverage and freshness.
- Usage may be subject to Tavily's rate limits and pricing tiers.
- The agent will only search when it determines that external information is needed.
### Troubleshooting
If you encounter issues with the search functionality:
- Verify that your API key is correct and active
- Check that your API key starts with `tvly-`
- Ensure you have an active internet connection
- Check Tavily's status page for any service disruptions
- Verify that your API key is correct and active.
- Check that your API key starts with `tvly-`.
- Ensure you have an active internet connection.
- Check Tavily's status page for any service disruptions.
instruction+='Image: To solve this task you will have to use the image shown below.\n\n'
image=Image.open(src_file)
ifextension_name=='jpg':
image_urls.append(image_to_jpg_base64_url(image))
else:
image_urls.append(image_to_png_base64_url(image))
instruction+="""IMPORTANT: When seeking information from a website, REFRAIN from arbitrary URL navigation. You should utilize the designated search engine tool with precise keywords to obtain relevant URLs or use the specific website's search interface. DO NOT navigate directly to specific URLs as they may not exist.\n\nFor example: if you want to search for a research paper on Arxiv, either use the search engine tool with specific keywords or navigate to arxiv.org and then use its interface.\n"""
instruction+='IMPORTANT: You should NEVER ask for Human Help.\n'
-`language`, the language of your evaluating dataset.
-`dataset`, the absolute position of the dataset jsonl.
**Skipping errors on build**
For debugging purposes, you can set `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=true` to continue evaluation even when instances reach maximum retries. After evaluation completes, check `maximum_retries_exceeded.jsonl` for a list of failed instances, fix those issues, and then run the evaluation again with `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=false`.
The results will be generated in evaluation/evaluation_outputs/outputs/XXX/CodeActAgent/YYY/output.jsonl, you can refer to the [example](examples/output.jsonl).
## Runing evaluation
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Engel Nyst
