{"id":31375935,"url":"https://github.com/dmisiuk/openhands-apple-silicon","last_synced_at":"2026-04-16T14:02:03.902Z","repository":{"id":316492168,"uuid":"1063604793","full_name":"dmisiuk/openhands-apple-silicon","owner":"dmisiuk","description":"🚀 Zero-config OpenHands setup for Apple Silicon Macs (M1/M2/M3/M4/M5+). Solves Docker compatibility issues and provides enhanced container management.","archived":false,"fork":false,"pushed_at":"2025-09-24T23:46:04.000Z","size":21,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T00:10:07.620Z","etag":null,"topics":["apple-silicon","arm64","containers","docker","m1","m2","m3","m4","macos","openhands"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmisiuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T21:27:20.000Z","updated_at":"2025-09-24T23:45:34.000Z","dependencies_parsed_at":"2025-09-25T00:10:15.044Z","dependency_job_id":null,"html_url":"https://github.com/dmisiuk/openhands-apple-silicon","commit_stats":null,"previous_names":["dmisiuk/openhands-apple-silicon"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dmisiuk/openhands-apple-silicon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmisiuk%2Fopenhands-apple-silicon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmisiuk%2Fopenhands-apple-silicon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmisiuk%2Fopenhands-apple-silicon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmisiuk%2Fopenhands-apple-silicon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmisiuk","download_url":"https://codeload.github.com/dmisiuk/openhands-apple-silicon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmisiuk%2Fopenhands-apple-silicon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31888935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-silicon","arm64","containers","docker","m1","m2","m3","m4","macos","openhands"],"created_at":"2025-09-28T02:51:56.396Z","updated_at":"2026-04-16T14:02:03.896Z","avatar_url":"https://github.com/dmisiuk.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 OpenHands for Apple Silicon (M1/M2/M3/M4/M5) - Easy Setup\n\n```\n  ╔══════════════════════════════════════════════════════════════╗\n  ║                                                              ║\n  ║    🍎 OPENHANDS FOR APPLE SILICON 🤖                         ║\n  ║                                                              ║\n  ║    ✨ Zero-config setup for M1/M2/M3 Macs                    ║\n  ║    🚀 Solves Docker + Runtime compatibility issues           ║\n  ║    🔧 One command to rule them all                           ║\n  ║                                                              ║\n  ║         [MacBook M1] ──❤️── [OpenHands AI]                   ║\n  ║                                                              ║\n  ║    📦 Ready to use  •  🧹 Auto cleanup  •  📊 Battle tested   ║\n  ║                                                              ║\n  ╚══════════════════════════════════════════════════════════════╝\n```\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![macOS](https://img.shields.io/badge/macOS-Apple%20Silicon-success)](https://support.apple.com/en-us/HT211814)\n[![Docker](https://img.shields.io/badge/Docker-Colima-blue)](https://github.com/abiosoft/colima)\n[![OpenHands](https://img.shields.io/badge/OpenHands-0.57.0-orange)](https://github.com/All-Hands-AI/OpenHands)\n\n\u003e **One-command solution for running OpenHands on Apple Silicon Macs (M1/M2/M3/M4/M5+)** 🍎\n\nGet [OpenHands](https://github.com/All-Hands-AI/OpenHands) (formerly OpenDevin) running smoothly on your Apple Silicon Mac with zero configuration headaches. This repository provides a battle-tested setup that solves all the common ARM64/Docker compatibility issues across the entire M-series chip lineup - from M1 to the latest M4 and future M5 processors.\n\n## ✨ Features\n\n- 🔧 **Zero-config setup** - Works out of the box on Apple Silicon\n- ⚡ **Fast startup** - Optimized container management\n- 🧹 **Smart cleanup** - Automatically manages Docker resources\n- 🔒 **Data persistence** - Your conversations survive restarts\n- 🎯 **M-series optimized** - Handles ARM64/AMD64 platform issues\n- 📱 **Browser control** - Start with or without auto-opening browser\n\n## 🚨 The Problem This Solves\n\nOpenHands users on Apple Silicon Macs commonly face:\n\n```\nRemoteProtocolError: Server disconnected without sending a response\nTargetClosedError: Target page, context or browser has been closed\nRuntime container failed to start\n```\n\n**Root causes:**\n- Playwright browser crashes in ARM64 containers\n- Platform architecture mismatches (ARM64 host ↔ AMD64 containers)\n- Insufficient Docker VM resources\n- Runtime image version conflicts\n\n## 🎯 The Solution\n\nOur setup provides:\n- ✅ **Explicit AMD64 platform specification** for M-series compatibility\n- ✅ **Proper runtime image versioning** (`0.57.0-nikolaik`)\n- ✅ **Browser actions disabled** to prevent Playwright crashes\n- ✅ **Optimized Docker resource allocation**\n- ✅ **Enhanced container cleanup** for better resource management\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n1. **macOS with Apple Silicon** - Any M-series chip (M1, M2, M3, M4, M5, or newer)\n2. **Colima + Docker** (recommended over Docker Desktop for performance)\n3. **Basic terminal knowledge**\n\n### Installation\n\n```bash\n# 1. Clone this repository\ngit clone https://github.com/dmisiuk/openhands-apple-silicon.git\ncd openhands-apple-silicon\n\n# 2. Make scripts executable\nchmod +x *.sh\n\n# 3. Set up Colima (if not already installed)\nbrew install colima docker\ncolima start --cpu 2 --memory 4 --disk 30\n\n# 4. Add aliases to your shell (optional but recommended)\necho 'alias oh-start=\\\"~/path/to/openhands-gui.sh start\\\"' \u003e\u003e ~/.zshrc\necho 'alias oh-stop=\\\"~/path/to/openhands-gui.sh stop\\\"' \u003e\u003e ~/.zshrc\necho 'alias oh-status=\\\"~/path/to/openhands-gui.sh status\\\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n## 🎮 Usage\n\n### Basic Commands\n\n```bash\n# Start OpenHands (no browser auto-open)\n./openhands-gui.sh start\n# OR with alias: oh-start\n\n# Start OpenHands + open browser automatically\n./openhands-gui.sh start-browser\n\n# Check status\n./openhands-gui.sh status\n# OR: oh-status\n\n# View logs\n./openhands-gui.sh logs\n\n# Stop and cleanup\n./openhands-gui.sh stop\n# OR: oh-stop\n\n# Restart\n./openhands-gui.sh restart\n```\n\n### Daily Workflow\n\n**Morning:**\n```bash\noh-start  # Starts in background, no browser popup\n```\nThen manually open http://localhost:3000 when ready to work.\n\n\u003e Works seamlessly on all Apple Silicon Macs - M1, M2, M3, M4, M5, and future processors\n\n**Evening:**\n```bash\noh-stop   # Stops containers, cleans up resources\n```\n\n### Advanced Usage\n\n**Environment Configuration:**\nCreate `~/.openhands_env` for custom settings:\n```bash\n# Example environment overrides\nSANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:custom-tag\nLOG_ALL_EVENTS=false\n# Add other OpenHands environment variables\n```\n\n**Resource Management:**\n```bash\n# Increase Colima resources if needed\ncolima stop\ncolima start --cpu 4 --memory 8 --disk 50\n\n# Check Docker resources\ndocker system df\n```\n\n**Colima Management:**\n```bash\n# The script does NOT stop Colima automatically (by design)\n# This allows other Docker projects to keep running\n\n# To manually stop Colima (saves battery):\ncolima stop\n\n# To restart Colima:\ncolima start --cpu 2 --memory 4 --disk 30\n```\n\n## 🔧 Configuration Details\n\n### Key Technical Solutions\n\n1. **Platform Specification:**\n   ```bash\n   export DOCKER_DEFAULT_PLATFORM=linux/amd64\n   ```\n   Forces AMD64 containers even on ARM64 hosts.\n\n2. **Runtime Image Version:**\n   ```bash\n   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.57.0-nikolaik\n   ```\n   Uses the M1-compatible runtime image variant.\n\n3. **Browser Actions Disabled:**\n   ```bash\n   -e BROWSER_ACTION_ENABLED=false\n   ```\n   Prevents Playwright crashes in containerized environments.\n\n4. **Enhanced Cleanup:**\n   - Removes main OpenHands container\n   - Cleans up runtime containers automatically\n   - Prunes stopped containers safely\n   - Preserves user data in `~/.openhands/`\n\n### File Structure\n\n```\nopenhands-apple-silicon/\n├── openhands-gui.sh     # Main launcher script\n├── README.md            # This file\n├── .gitignore          # Protects private data\n└── LICENSE             # MIT license\n```\n\n## 🧪 System Tested\n\n**Actually tested and confirmed working:**\n- ✅ **M1 MacBook** running **macOS Sequoia 15.7**\n- ✅ **Docker via Colima** (recommended setup)\n- ✅ **OpenHands version 0.57.0** with runtime:0.57.0-nikolaik\n\n**Expected to work (same architecture):**\n- 🔄 M2, M3, M4, M5 Macs (same ARM64 architecture, same Docker compatibility issues)\n- 🔄 macOS Big Sur 11.0+ through latest versions\n- 🔄 Docker Desktop (though Colima recommended for performance)\n\n*Community testing and feedback welcome for other configurations!*\n\n## 📊 What Gets Persisted?\n\n**✅ Saved (survives restarts):**\n- All conversation history (`~/.openhands/sessions/`)\n- User settings and preferences (`~/.openhands/settings.json`)\n- Authentication tokens (`~/.openhands/.jwt_secret`)\n- Configuration files (`~/.openhands/config.toml`)\n\n**❌ Temporary (cleaned on stop):**\n- Container processes and runtime state\n- Temporary execution environments\n- Container logs (use `docker logs` while running)\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"Container failed to start\"**\n```bash\n# Check Docker is running\ndocker info\n\n# Restart Colima if needed\ncolima restart\n\n# Check resources\ndocker system df\n```\n\n**\"Runtime image not found\"**\n```bash\n# Verify the runtime image exists\ndocker pull docker.all-hands.dev/all-hands-ai/runtime:0.57.0-nikolaik\n```\n\n**\"Port 3000 already in use\"**\n```bash\n# Find what's using port 3000\nlsof -i :3000\n\n# Stop previous OpenHands instance\n./openhands-gui.sh stop\n```\n\n**\"Out of disk space\"**\n```bash\n# Clean Docker system\ndocker system prune -af --volumes\n\n# Increase Colima disk size\ncolima stop\ncolima start --cpu 2 --memory 4 --disk 50\n```\n\n### Debug Mode\n\nRun with verbose logging:\n```bash\nLOG_ALL_EVENTS=true ./openhands-gui.sh start\n```\n\n## 🙏 Contributing\n\nContributions welcome! This setup has been battle-tested but we're always improving.\n\n### Areas for Contribution:\n- 🧪 Testing on newer OpenHands versions\n- 📚 Documentation improvements\n- 🔧 Additional M-series optimizations\n- 🐛 Bug fixes and edge cases\n- 🌟 Feature enhancements\n\n### How to Contribute:\n1. Fork this repository\n2. Create a feature branch\n3. Test on your M-series Mac\n4. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌟 Acknowledgments\n\n- **OpenHands Team** - For the amazing AI coding assistant\n- **GitHub Issue #7618** - Community solution that inspired this setup\n- **Apple Silicon Community** - For documenting Docker compatibility issues\n- **Colima Project** - For the excellent Docker Desktop alternative\n\n## 🔗 Related Links\n\n- [OpenHands Official Repo](https://github.com/All-Hands-AI/OpenHands)\n- [Colima Documentation](https://github.com/abiosoft/colima)\n- [Docker on Apple Silicon](https://docs.docker.com/desktop/mac/apple-silicon/)\n- [Original GitHub Issue #7618](https://github.com/All-Hands-AI/OpenHands/issues/7618)\n\n---\n\n**⭐ Star this repo if it helped you get OpenHands running on your Mac!**\n\n**🐛 Found an issue?** [Open an issue](../../issues) and we'll help you out.\n\n**💬 Questions?** [Start a discussion](../../discussions) with the community.\n\n---\n\n*Made with ❤️ for the Apple Silicon community*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmisiuk%2Fopenhands-apple-silicon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmisiuk%2Fopenhands-apple-silicon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmisiuk%2Fopenhands-apple-silicon/lists"}