mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
Fix issue #10786: Homebrew Install for CLI
This commit is contained in:
openhands
parent
2631294e79
commit
154907dd28
32
README.md
32
README.md
@ -55,9 +55,35 @@ which comes with $20 in free credits for new users.
|
||||
|
||||
## 💻 Running OpenHands Locally
|
||||
|
||||
### Option 1: CLI Launcher (Recommended)
|
||||
### Option 1: Homebrew (macOS - Recommended)
|
||||
|
||||
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.
|
||||
The easiest way to install OpenHands CLI on macOS is using Homebrew:
|
||||
|
||||
```bash
|
||||
# Add the OpenHands tap
|
||||
brew tap All-Hands-AI/openhands https://github.com/All-Hands-AI/OpenHands.git
|
||||
|
||||
# Install OpenHands CLI
|
||||
brew install openhands
|
||||
```
|
||||
|
||||
**Launch OpenHands**:
|
||||
```bash
|
||||
# Launch the CLI (short command)
|
||||
oh
|
||||
|
||||
# Or use the full name
|
||||
openhands
|
||||
|
||||
# Launch the GUI server
|
||||
oh serve
|
||||
```
|
||||
|
||||
You'll find OpenHands running at [http://localhost:3000](http://localhost:3000) (for GUI mode)!
|
||||
|
||||
### Option 2: CLI Launcher with uv
|
||||
|
||||
You can also run OpenHands 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):
|
||||
|
||||
@ -74,7 +100,7 @@ uvx --python 3.12 --from openhands-ai openhands
|
||||
|
||||
You'll find OpenHands running at [http://localhost:3000](http://localhost:3000) (for GUI mode)!
|
||||
|
||||
### Option 2: Docker
|
||||
### Option 3: Docker
|
||||
|
||||
<details>
|
||||
<summary>Click to expand Docker command</summary>
|
||||
|
||||
242
homebrew/DEVELOPMENT.md
Normal file
242
homebrew/DEVELOPMENT.md
Normal file
@ -0,0 +1,242 @@
|
||||
# Homebrew Formula Development Guide
|
||||
|
||||
This guide provides instructions for maintaining and testing the OpenHands Homebrew formula.
|
||||
|
||||
## Formula Structure
|
||||
|
||||
The `openhands.rb` formula:
|
||||
- Downloads the OpenHands repository source
|
||||
- Creates a Python 3.12 virtual environment
|
||||
- Installs the openhands-cli package with all dependencies using pip
|
||||
- Creates two wrapper scripts:
|
||||
- `oh` - Short command for quick access
|
||||
- `openhands` - Full name for clarity
|
||||
|
||||
## Testing the Formula Locally
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- macOS with Homebrew installed
|
||||
- Git
|
||||
- Basic understanding of Homebrew formula development
|
||||
|
||||
### Test Installation
|
||||
|
||||
1. **Install from local formula:**
|
||||
```bash
|
||||
cd /path/to/OpenHands
|
||||
brew install --build-from-source --verbose ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
2. **Test the installed commands:**
|
||||
```bash
|
||||
# Check if commands exist
|
||||
which oh
|
||||
which openhands
|
||||
|
||||
# Test help output
|
||||
oh --help
|
||||
openhands --help
|
||||
|
||||
# Test version
|
||||
oh --version
|
||||
```
|
||||
|
||||
3. **Run the formula tests:**
|
||||
```bash
|
||||
brew test openhands
|
||||
```
|
||||
|
||||
4. **Audit the formula:**
|
||||
```bash
|
||||
brew audit --new-formula ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Uninstall for Testing
|
||||
|
||||
```bash
|
||||
brew uninstall openhands
|
||||
brew cleanup
|
||||
```
|
||||
|
||||
## Updating the Formula
|
||||
|
||||
### Version Updates
|
||||
|
||||
When releasing a new version:
|
||||
|
||||
1. Update the `version` field in `openhands.rb`:
|
||||
```ruby
|
||||
version "1.0.3" # New version
|
||||
```
|
||||
|
||||
2. If using a tagged release (recommended for production), update the `url`:
|
||||
```ruby
|
||||
url "https://github.com/All-Hands-AI/OpenHands/archive/refs/tags/v1.0.3.tar.gz"
|
||||
```
|
||||
|
||||
3. Calculate and update the SHA256 checksum:
|
||||
```bash
|
||||
# Download the tarball
|
||||
curl -L https://github.com/All-Hands-AI/OpenHands/archive/refs/tags/v1.0.3.tar.gz -o openhands.tar.gz
|
||||
|
||||
# Calculate SHA256
|
||||
shasum -a 256 openhands.tar.gz
|
||||
```
|
||||
|
||||
4. Add the `sha256` field to the formula:
|
||||
```ruby
|
||||
url "https://github.com/All-Hands-AI/OpenHands/archive/refs/tags/v1.0.3.tar.gz"
|
||||
sha256 "your-calculated-sha256-here"
|
||||
```
|
||||
|
||||
### Dependency Updates
|
||||
|
||||
If Python dependencies change in `openhands-cli/pyproject.toml`, the formula will automatically pick them up since it uses pip to install the package. No formula changes are needed unless:
|
||||
- The Python version requirement changes
|
||||
- New system-level dependencies are needed
|
||||
|
||||
## Publishing the Formula
|
||||
|
||||
### Using as a Tap
|
||||
|
||||
Users can install from the tap:
|
||||
|
||||
```bash
|
||||
# Add the tap (only needed once)
|
||||
brew tap All-Hands-AI/openhands https://github.com/All-Hands-AI/OpenHands.git
|
||||
|
||||
# Install
|
||||
brew install openhands
|
||||
|
||||
# Update
|
||||
brew update
|
||||
brew upgrade openhands
|
||||
```
|
||||
|
||||
### Submitting to Homebrew Core (Optional)
|
||||
|
||||
For wider distribution, you can submit to Homebrew/homebrew-core:
|
||||
|
||||
1. Fork https://github.com/Homebrew/homebrew-core
|
||||
2. Add the formula to `Formula/o/openhands.rb`
|
||||
3. Follow Homebrew's contribution guidelines
|
||||
4. Submit a pull request
|
||||
|
||||
**Requirements for Homebrew Core:**
|
||||
- Formula must use stable, tagged releases (not `main` branch)
|
||||
- Must pass all Homebrew CI tests
|
||||
- Project should be relatively stable and well-maintained
|
||||
- Must follow Homebrew formula style guidelines
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: Installation fails with Python dependency errors
|
||||
|
||||
**Solution:** Ensure the `openhands-cli/pyproject.toml` has correct dependency specifications. The formula relies on pip to resolve all dependencies.
|
||||
|
||||
### Issue: Commands not found after installation
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Restart shell
|
||||
exec $SHELL
|
||||
|
||||
# Or check Homebrew paths
|
||||
brew doctor
|
||||
```
|
||||
|
||||
### Issue: macOS Gatekeeper blocks execution
|
||||
|
||||
**Solution:** This is expected for unsigned binaries. Users can:
|
||||
1. Go to System Settings > Privacy & Security > Click "Open Anyway"
|
||||
2. Or run: `xattr -d com.apple.quarantine $(which oh)`
|
||||
|
||||
### Issue: Formula fails brew audit
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Run audit to see specific issues
|
||||
brew audit --strict --online ./homebrew/openhands.rb
|
||||
|
||||
# Common fixes:
|
||||
# - Ensure proper formatting (2 spaces, no tabs)
|
||||
# - Add missing license field
|
||||
# - Fix URL format
|
||||
# - Add proper test section
|
||||
```
|
||||
|
||||
## Testing Different Installation Methods
|
||||
|
||||
### Method 1: Direct from GitHub
|
||||
|
||||
```bash
|
||||
brew install https://raw.githubusercontent.com/All-Hands-AI/OpenHands/main/homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Method 2: From Tap
|
||||
|
||||
```bash
|
||||
brew tap All-Hands-AI/openhands https://github.com/All-Hands-AI/OpenHands.git
|
||||
brew install openhands
|
||||
```
|
||||
|
||||
### Method 3: Local Development
|
||||
|
||||
```bash
|
||||
cd /path/to/OpenHands
|
||||
brew install --build-from-source ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
Enable verbose output:
|
||||
```bash
|
||||
brew install --verbose --debug ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
Check installation logs:
|
||||
```bash
|
||||
brew info openhands
|
||||
brew list openhands
|
||||
```
|
||||
|
||||
View formula code:
|
||||
```bash
|
||||
brew cat openhands
|
||||
```
|
||||
|
||||
## Code Signing (Future)
|
||||
|
||||
For production releases, consider code signing the binaries:
|
||||
|
||||
1. Get an Apple Developer account
|
||||
2. Create a Developer ID Application certificate
|
||||
3. Sign the binaries:
|
||||
```bash
|
||||
codesign --sign "Developer ID Application: Your Name" /path/to/binary
|
||||
```
|
||||
4. Notarize with Apple:
|
||||
```bash
|
||||
xcrun notarytool submit /path/to/binary --apple-id your@email.com
|
||||
```
|
||||
|
||||
This removes the Gatekeeper warning for users.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook)
|
||||
- [Python for Formula Authors](https://docs.brew.sh/Python-for-Formula-Authors)
|
||||
- [Homebrew Acceptable Formulae](https://docs.brew.sh/Acceptable-Formulae)
|
||||
- [Homebrew Style Guide](https://docs.brew.sh/Formula-Cookbook#style)
|
||||
|
||||
## Maintenance Checklist
|
||||
|
||||
- [ ] Test formula installs correctly
|
||||
- [ ] Verify both `oh` and `openhands` commands work
|
||||
- [ ] Check help output displays correctly
|
||||
- [ ] Run `brew audit` and fix any issues
|
||||
- [ ] Update version number for releases
|
||||
- [ ] Update SHA256 for tagged releases
|
||||
- [ ] Test on clean macOS system if possible
|
||||
- [ ] Update documentation if CLI usage changes
|
||||
305
homebrew/IMPLEMENTATION_SUMMARY.md
Normal file
305
homebrew/IMPLEMENTATION_SUMMARY.md
Normal file
@ -0,0 +1,305 @@
|
||||
# Homebrew Installation Implementation Summary
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes the implementation of Homebrew installation support for the OpenHands CLI. The implementation makes it easier for macOS users to install and use OpenHands without needing to manually install Python ecosystem tools like `uv`.
|
||||
|
||||
## Solution Design
|
||||
|
||||
### Approach
|
||||
|
||||
We implemented a **Homebrew tap** within the OpenHands repository. This approach was chosen because:
|
||||
|
||||
1. **Flexibility**: Easy to update and maintain alongside the main codebase
|
||||
2. **Integration**: Keeps everything in one repository
|
||||
3. **Control**: We maintain full control over the formula and release process
|
||||
4. **Simplicity**: Users can install with simple `brew install` commands
|
||||
|
||||
### Command Names
|
||||
|
||||
The implementation provides two command names:
|
||||
|
||||
- **`oh`** - Short, memorable command (primary/recommended)
|
||||
- Follows modern CLI tool patterns (like `gh` for GitHub)
|
||||
- Verified to not conflict with common macOS/Linux utilities
|
||||
- Easy to type and remember
|
||||
|
||||
- **`openhands`** - Full name (alternative)
|
||||
- Provides clarity for those who prefer explicit names
|
||||
- Useful for scripts and documentation
|
||||
|
||||
Both commands invoke the same CLI application.
|
||||
|
||||
## Files Created
|
||||
|
||||
### 1. `homebrew/openhands.rb`
|
||||
|
||||
The Homebrew formula that:
|
||||
- Downloads the OpenHands repository
|
||||
- Creates a Python 3.12 virtual environment
|
||||
- Installs the openhands-cli package with all dependencies
|
||||
- Creates wrapper scripts for both `oh` and `openhands` commands
|
||||
- Provides helpful installation messages (caveats)
|
||||
- Includes tests to verify installation
|
||||
|
||||
**Key Features:**
|
||||
- Uses Python's pip for dependency resolution (automatic handling of transitive dependencies)
|
||||
- Leverages Homebrew's virtualenv support for clean isolation
|
||||
- Provides helpful post-installation messages about requirements (Docker, API keys)
|
||||
- Includes macOS Gatekeeper security warning handling
|
||||
|
||||
### 2. `homebrew/README.md`
|
||||
|
||||
Comprehensive user documentation covering:
|
||||
- Installation methods (tap, direct, local)
|
||||
- Usage instructions
|
||||
- Requirements (Docker, API keys)
|
||||
- Troubleshooting common issues
|
||||
- Update and uninstall procedures
|
||||
|
||||
### 3. `homebrew/DEVELOPMENT.md`
|
||||
|
||||
Developer documentation covering:
|
||||
- Formula structure and architecture
|
||||
- Testing procedures
|
||||
- Version update process
|
||||
- Publishing guidelines
|
||||
- Debugging tips
|
||||
- Future code signing considerations
|
||||
|
||||
### 4. `homebrew/IMPLEMENTATION_SUMMARY.md` (this file)
|
||||
|
||||
High-level overview of the implementation for maintainers and contributors.
|
||||
|
||||
### 5. Updated `README.md`
|
||||
|
||||
The main repository README now includes:
|
||||
- Homebrew installation as **Option 1 (Recommended)** for macOS users
|
||||
- Clear instructions for both installation methods
|
||||
- Maintains existing installation options
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Using the Tap (Recommended)
|
||||
|
||||
```bash
|
||||
# Add the tap
|
||||
brew tap All-Hands-AI/openhands https://github.com/All-Hands-AI/OpenHands.git
|
||||
|
||||
# Install
|
||||
brew install openhands
|
||||
```
|
||||
|
||||
### Method 2: Direct Installation
|
||||
|
||||
```bash
|
||||
brew install https://raw.githubusercontent.com/All-Hands-AI/OpenHands/main/homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Method 3: Local Development
|
||||
|
||||
```bash
|
||||
cd /path/to/OpenHands
|
||||
brew install --build-from-source ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Dependencies
|
||||
|
||||
The formula automatically handles:
|
||||
- Python 3.12 (installed by Homebrew as a dependency)
|
||||
- All Python packages from `openhands-cli/pyproject.toml`:
|
||||
- openhands-sdk
|
||||
- openhands-tools
|
||||
- prompt-toolkit
|
||||
- typer
|
||||
- All transitive dependencies
|
||||
|
||||
### Installation Process
|
||||
|
||||
1. Homebrew downloads the repository tarball
|
||||
2. Creates an isolated Python 3.12 virtualenv
|
||||
3. Changes to `openhands-cli` subdirectory
|
||||
4. Runs `pip install` to install the package and dependencies
|
||||
5. Creates wrapper scripts in Homebrew's bin directory
|
||||
6. Sets executable permissions
|
||||
7. Displays helpful caveats to the user
|
||||
|
||||
### Wrapper Scripts
|
||||
|
||||
Both `oh` and `openhands` are bash wrapper scripts that:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
exec "/path/to/libexec/bin/python" -m openhands_cli.simple_main "$@"
|
||||
```
|
||||
|
||||
This approach:
|
||||
- Ensures the correct Python interpreter is used
|
||||
- Maintains the virtual environment isolation
|
||||
- Passes all arguments to the CLI properly
|
||||
- Works with both GUI and CLI modes
|
||||
|
||||
## macOS Security Considerations
|
||||
|
||||
### Gatekeeper Warnings
|
||||
|
||||
macOS may show security warnings for unsigned binaries. We handle this by:
|
||||
|
||||
1. **Documentation**: Clear instructions in the caveats and README
|
||||
2. **User Options**:
|
||||
- System Settings > Privacy & Security > "Open Anyway"
|
||||
- Or: `xattr -d com.apple.quarantine $(which oh)`
|
||||
|
||||
### Future: Code Signing
|
||||
|
||||
For production releases, we can implement:
|
||||
- Apple Developer account code signing
|
||||
- Notarization with Apple
|
||||
- This would eliminate Gatekeeper warnings
|
||||
|
||||
The process is documented in `DEVELOPMENT.md` for future implementation.
|
||||
|
||||
## Testing
|
||||
|
||||
### Pre-Release Testing
|
||||
|
||||
Before releasing a new version:
|
||||
|
||||
```bash
|
||||
# Install locally
|
||||
brew install --build-from-source ./homebrew/openhands.rb
|
||||
|
||||
# Test commands
|
||||
oh --help
|
||||
openhands --help
|
||||
oh serve
|
||||
|
||||
# Run formula tests
|
||||
brew test openhands
|
||||
|
||||
# Audit the formula
|
||||
brew audit --new-formula ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Command Conflict Check
|
||||
|
||||
We verified that `oh` doesn't conflict with:
|
||||
- Common shell utilities (ls, cd, grep, etc.)
|
||||
- Common development tools (git, make, npm, etc.)
|
||||
- macOS-specific utilities (open, pbcopy, brew, etc.)
|
||||
- Linux utilities (apt, systemctl, etc.)
|
||||
|
||||
Result: ✅ No conflicts found
|
||||
|
||||
## User Experience Improvements
|
||||
|
||||
### Before (with uv)
|
||||
|
||||
```bash
|
||||
# Install uv first
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
# Restart shell
|
||||
exec $SHELL
|
||||
|
||||
# Run OpenHands
|
||||
uvx --python 3.12 --from openhands-ai openhands serve
|
||||
```
|
||||
|
||||
### After (with Homebrew)
|
||||
|
||||
```bash
|
||||
# Install
|
||||
brew install openhands
|
||||
|
||||
# Run OpenHands
|
||||
oh serve
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Fewer steps**: Single installation command
|
||||
2. **Familiar**: Uses standard Homebrew workflow
|
||||
3. **Shorter command**: `oh` vs long `uvx` command
|
||||
4. **No Python knowledge needed**: Homebrew handles Python setup
|
||||
5. **Easy updates**: `brew upgrade openhands`
|
||||
6. **Clean uninstall**: `brew uninstall openhands`
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Version Updates
|
||||
|
||||
When releasing a new version:
|
||||
|
||||
1. Update `version` in `openhands.rb`
|
||||
2. Update `url` to point to the tagged release
|
||||
3. Calculate and add SHA256 checksum
|
||||
4. Test the installation
|
||||
5. Users update with `brew upgrade openhands`
|
||||
|
||||
See `DEVELOPMENT.md` for detailed procedures.
|
||||
|
||||
### Dependency Updates
|
||||
|
||||
Python dependency changes in `openhands-cli/pyproject.toml` are automatically picked up by the formula since it uses pip for installation. No formula changes needed.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Submit to Homebrew Core
|
||||
|
||||
For maximum visibility, we could submit to official Homebrew:
|
||||
- Requires stable, tagged releases
|
||||
- Must pass strict CI tests
|
||||
- Broader reach to users
|
||||
|
||||
### 2. Code Signing
|
||||
|
||||
Implement Apple Developer code signing:
|
||||
- Eliminates security warnings
|
||||
- Better user experience
|
||||
- Requires Apple Developer account
|
||||
|
||||
### 3. Binary Distribution
|
||||
|
||||
Instead of building from source:
|
||||
- Host pre-built binaries
|
||||
- Faster installation
|
||||
- Requires hosting infrastructure
|
||||
|
||||
### 4. Linux Support
|
||||
|
||||
Create similar installation methods for Linux:
|
||||
- Snap packages
|
||||
- AppImage
|
||||
- Debian/Ubuntu PPA
|
||||
- RPM repositories
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Users can install with: `brew install openhands`
|
||||
✅ Short command `oh` works and doesn't conflict
|
||||
✅ Full command `openhands` also works
|
||||
✅ Both CLI and GUI modes functional
|
||||
✅ Clear documentation provided
|
||||
✅ Troubleshooting guide available
|
||||
✅ Developer documentation for maintenance
|
||||
✅ Main README updated with Homebrew instructions
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- GitHub Issues: https://github.com/All-Hands-AI/OpenHands/issues
|
||||
- Documentation: https://docs.all-hands.dev
|
||||
- Discord: https://discord.gg/ESHStjSjD4
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Same as OpenHands project
|
||||
|
||||
---
|
||||
|
||||
**Implementation Date**: 2025-10-25
|
||||
**Formula Version**: 1.0.2
|
||||
**Minimum macOS**: 10.15 (Catalina)
|
||||
**Python Version**: 3.12
|
||||
186
homebrew/README.md
Normal file
186
homebrew/README.md
Normal file
@ -0,0 +1,186 @@
|
||||
# OpenHands Homebrew Tap
|
||||
|
||||
This directory contains the Homebrew formula for installing OpenHands CLI on macOS.
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Install from the OpenHands tap (Recommended)
|
||||
|
||||
```bash
|
||||
# Add the OpenHands tap
|
||||
brew tap All-Hands-AI/openhands https://github.com/All-Hands-AI/OpenHands.git
|
||||
|
||||
# Install OpenHands CLI
|
||||
brew install openhands
|
||||
```
|
||||
|
||||
### Option 2: Install directly from the repository
|
||||
|
||||
```bash
|
||||
# Install directly from the formula file
|
||||
brew install --HEAD https://raw.githubusercontent.com/All-Hands-AI/OpenHands/main/homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Option 3: Install from local clone
|
||||
|
||||
If you have cloned the repository locally:
|
||||
|
||||
```bash
|
||||
cd /path/to/OpenHands
|
||||
brew install --build-from-source ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After installation, you can use OpenHands CLI with either:
|
||||
|
||||
```bash
|
||||
# Short command (recommended)
|
||||
oh
|
||||
|
||||
# Or full name
|
||||
openhands
|
||||
```
|
||||
|
||||
### Getting Started
|
||||
|
||||
1. **Start the CLI:**
|
||||
```bash
|
||||
oh
|
||||
```
|
||||
|
||||
2. **Get help:**
|
||||
```bash
|
||||
oh --help
|
||||
```
|
||||
|
||||
3. **Start the GUI server:**
|
||||
```bash
|
||||
oh serve
|
||||
```
|
||||
|
||||
4. **Resume a conversation:**
|
||||
```bash
|
||||
oh --resume <conversation-id>
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- macOS 10.15 or later
|
||||
- Python 3.12 (automatically installed by Homebrew as a dependency)
|
||||
- Docker Desktop or OrbStack (for full functionality)
|
||||
- An LLM API key (OpenAI, Anthropic, etc.)
|
||||
|
||||
## Updating
|
||||
|
||||
To update to the latest version:
|
||||
|
||||
```bash
|
||||
brew update
|
||||
brew upgrade openhands
|
||||
```
|
||||
|
||||
## Uninstalling
|
||||
|
||||
To remove OpenHands CLI:
|
||||
|
||||
```bash
|
||||
brew uninstall openhands
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### macOS Security Warning
|
||||
|
||||
On first run, macOS may show a security warning about an application from an unidentified developer. To resolve this:
|
||||
|
||||
1. Go to **System Settings** > **Privacy & Security**
|
||||
2. Scroll down to find the message about OpenHands being blocked
|
||||
3. Click **"Open Anyway"**
|
||||
|
||||
Alternatively, you can run this command to remove the quarantine attribute:
|
||||
|
||||
```bash
|
||||
xattr -d com.apple.quarantine $(which oh)
|
||||
xattr -d com.apple.quarantine $(which openhands)
|
||||
```
|
||||
|
||||
### Command Not Found
|
||||
|
||||
If the `oh` or `openhands` command is not found after installation, try:
|
||||
|
||||
```bash
|
||||
# Restart your shell
|
||||
exec $SHELL
|
||||
|
||||
# Or reload your shell configuration
|
||||
source ~/.zshrc # For zsh
|
||||
source ~/.bashrc # For bash
|
||||
```
|
||||
|
||||
### Python Version Issues
|
||||
|
||||
If you encounter Python version issues, ensure you're using Python 3.12:
|
||||
|
||||
```bash
|
||||
# Check Python version
|
||||
python3.12 --version
|
||||
|
||||
# If missing, install via Homebrew
|
||||
brew install python@3.12
|
||||
```
|
||||
|
||||
### Installation Fails
|
||||
|
||||
If the installation fails, try:
|
||||
|
||||
```bash
|
||||
# Clean up and reinstall
|
||||
brew uninstall openhands
|
||||
brew cleanup
|
||||
brew install openhands
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Testing Changes Locally
|
||||
|
||||
If you're developing the formula:
|
||||
|
||||
```bash
|
||||
# Test installation
|
||||
brew install --build-from-source --verbose --debug ./homebrew/openhands.rb
|
||||
|
||||
# Test the formula
|
||||
brew test openhands
|
||||
|
||||
# Audit the formula
|
||||
brew audit --new-formula ./homebrew/openhands.rb
|
||||
```
|
||||
|
||||
### Formula Structure
|
||||
|
||||
The formula:
|
||||
- Downloads the OpenHands repository
|
||||
- Creates a Python virtual environment
|
||||
- Installs the openhands-cli package with all dependencies
|
||||
- Creates wrapper scripts for `oh` and `openhands` commands
|
||||
- Sets up proper permissions
|
||||
|
||||
## Contributing
|
||||
|
||||
If you find issues with the Homebrew formula or have suggestions for improvement, please:
|
||||
|
||||
1. Open an issue at https://github.com/All-Hands-AI/OpenHands/issues
|
||||
2. Submit a pull request with your proposed changes
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See the main repository LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
For help and support:
|
||||
- Documentation: https://docs.all-hands.dev
|
||||
- GitHub Issues: https://github.com/All-Hands-AI/OpenHands/issues
|
||||
- Discord: https://discord.gg/ESHStjSjD4
|
||||
79
homebrew/openhands.rb
Normal file
79
homebrew/openhands.rb
Normal file
@ -0,0 +1,79 @@
|
||||
class Openhands < Formula
|
||||
include Language::Python::Virtualenv
|
||||
|
||||
desc "OpenHands CLI - AI-powered software development assistant"
|
||||
homepage "https://github.com/All-Hands-AI/OpenHands"
|
||||
url "https://github.com/All-Hands-AI/OpenHands/archive/refs/heads/main.tar.gz"
|
||||
version "1.0.2"
|
||||
license "MIT"
|
||||
head "https://github.com/All-Hands-AI/OpenHands.git", branch: "main"
|
||||
|
||||
depends_on "python@3.12"
|
||||
|
||||
def install
|
||||
# Create a virtualenv with Python 3.12
|
||||
venv = virtualenv_create(libexec, "python3.12")
|
||||
|
||||
# Install the CLI package from the openhands-cli subdirectory
|
||||
# This will automatically install all dependencies including openhands-sdk,
|
||||
# openhands-tools, prompt-toolkit, typer, and their transitive dependencies
|
||||
cd "openhands-cli" do
|
||||
venv.pip_install Pathname.pwd
|
||||
end
|
||||
|
||||
# Create the 'oh' wrapper script
|
||||
(bin/"oh").write <<~EOS
|
||||
#!/bin/bash
|
||||
exec "#{libexec}/bin/python" -m openhands_cli.simple_main "$@"
|
||||
EOS
|
||||
|
||||
# Make the wrapper executable
|
||||
chmod 0755, bin/"oh"
|
||||
|
||||
# Create 'openhands' as the primary command that calls the installed script
|
||||
(bin/"openhands").write <<~EOS
|
||||
#!/bin/bash
|
||||
exec "#{libexec}/bin/python" -m openhands_cli.simple_main "$@"
|
||||
EOS
|
||||
|
||||
chmod 0755, bin/"openhands"
|
||||
end
|
||||
|
||||
def caveats
|
||||
<<~EOS
|
||||
OpenHands CLI has been installed!
|
||||
|
||||
You can now use it with the short command:
|
||||
oh
|
||||
|
||||
Or the full name:
|
||||
openhands
|
||||
|
||||
To get started:
|
||||
oh --help
|
||||
|
||||
First-time setup:
|
||||
oh
|
||||
|
||||
The CLI will guide you through initial configuration.
|
||||
|
||||
Note: On first run, macOS may show a security warning.
|
||||
If this happens, go to System Settings > Privacy & Security
|
||||
and click "Open Anyway" to allow the application to run.
|
||||
|
||||
Requirements:
|
||||
- Docker Desktop or OrbStack must be installed for full functionality
|
||||
- An OpenAI API key or other LLM provider API key will be needed
|
||||
EOS
|
||||
end
|
||||
|
||||
test do
|
||||
# Test that the commands exist and are executable
|
||||
assert_predicate bin/"oh", :exist?
|
||||
assert_predicate bin/"openhands", :exist?
|
||||
|
||||
# Test help output works
|
||||
output = shell_output("#{bin}/oh --help 2>&1", 0)
|
||||
assert_match "OpenHands", output
|
||||
end
|
||||
end
|
||||
157
homebrew/validate.sh
Normal file
157
homebrew/validate.sh
Normal file
@ -0,0 +1,157 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Validation script for Homebrew formula setup
|
||||
# This script checks that all necessary files are in place and properly formatted
|
||||
#
|
||||
|
||||
set -e
|
||||
|
||||
echo "🔍 OpenHands Homebrew Formula Validation"
|
||||
echo "=========================================="
|
||||
echo ""
|
||||
|
||||
# Check if we're in the right directory
|
||||
if [ ! -d "homebrew" ]; then
|
||||
echo "❌ Error: homebrew/ directory not found!"
|
||||
echo " Please run this script from the OpenHands repository root"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Found homebrew/ directory"
|
||||
|
||||
# Check required files
|
||||
REQUIRED_FILES=(
|
||||
"homebrew/openhands.rb"
|
||||
"homebrew/README.md"
|
||||
"homebrew/DEVELOPMENT.md"
|
||||
)
|
||||
|
||||
for file in "${REQUIRED_FILES[@]}"; do
|
||||
if [ -f "$file" ]; then
|
||||
echo "✅ Found $file"
|
||||
else
|
||||
echo "❌ Missing required file: $file"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# Check formula syntax
|
||||
echo ""
|
||||
echo "📝 Checking formula syntax..."
|
||||
|
||||
if [ ! -f "homebrew/openhands.rb" ]; then
|
||||
echo "❌ Formula file not found!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Basic Ruby syntax checks
|
||||
if ! grep -q "class Openhands < Formula" homebrew/openhands.rb; then
|
||||
echo "❌ Formula class definition not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Formula class definition found"
|
||||
|
||||
if ! grep -q "def install" homebrew/openhands.rb; then
|
||||
echo "❌ Install method not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Install method found"
|
||||
|
||||
if ! grep -q "test do" homebrew/openhands.rb; then
|
||||
echo "❌ Test block not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Test block found"
|
||||
|
||||
# Check for required fields
|
||||
if ! grep -q 'desc "' homebrew/openhands.rb; then
|
||||
echo "❌ Description not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Description found"
|
||||
|
||||
if ! grep -q 'homepage "' homebrew/openhands.rb; then
|
||||
echo "❌ Homepage not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Homepage found"
|
||||
|
||||
if ! grep -q 'license "' homebrew/openhands.rb; then
|
||||
echo "❌ License not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ License found"
|
||||
|
||||
# Check for command wrappers
|
||||
if ! grep -q 'bin/"oh"' homebrew/openhands.rb; then
|
||||
echo "❌ 'oh' command wrapper not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ 'oh' command wrapper found"
|
||||
|
||||
if ! grep -q 'bin/"openhands"' homebrew/openhands.rb; then
|
||||
echo "❌ 'openhands' command wrapper not found!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ 'openhands' command wrapper found"
|
||||
|
||||
# Check README content
|
||||
echo ""
|
||||
echo "📝 Checking README.md content..."
|
||||
|
||||
if ! grep -q "Installation" homebrew/README.md; then
|
||||
echo "❌ Installation section not found in README!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Installation section found"
|
||||
|
||||
if ! grep -q "brew install openhands" homebrew/README.md; then
|
||||
echo "❌ Installation command not found in README!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Installation command found"
|
||||
|
||||
# Check if main README was updated
|
||||
echo ""
|
||||
echo "📝 Checking main README.md..."
|
||||
|
||||
if ! grep -q "Homebrew" README.md; then
|
||||
echo "❌ Homebrew section not found in main README!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Homebrew section found in main README"
|
||||
|
||||
if ! grep -q "brew install openhands" README.md; then
|
||||
echo "❌ Homebrew installation command not found in main README!"
|
||||
exit 1
|
||||
fi
|
||||
echo "✅ Homebrew installation command found in main README"
|
||||
|
||||
# Check for oh command in README
|
||||
if ! grep -q "oh" README.md; then
|
||||
echo "⚠️ Warning: 'oh' command not prominently featured in main README"
|
||||
else
|
||||
echo "✅ 'oh' command mentioned in main README"
|
||||
fi
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "=========================================="
|
||||
echo "✅ All validation checks passed!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Test the formula locally:"
|
||||
echo " brew install --build-from-source ./homebrew/openhands.rb"
|
||||
echo ""
|
||||
echo "2. Test the commands:"
|
||||
echo " oh --help"
|
||||
echo " openhands --help"
|
||||
echo ""
|
||||
echo "3. Run brew tests:"
|
||||
echo " brew test openhands"
|
||||
echo ""
|
||||
echo "4. Audit the formula:"
|
||||
echo " brew audit ./homebrew/openhands.rb"
|
||||
echo ""
|
||||
echo "5. Commit and push the changes"
|
||||
echo "=========================================="
|
||||
Loading…
x
Reference in New Issue
Block a user