APPLICATION_README.md

metadata

title: Chrome Controller Pro
emoji: 🌐
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860

Chrome Controller Pro

A professional-grade Chrome browser controller for Hugging Face Spaces with advanced automation capabilities.

🚀 Features

• Headless Chrome Management: Start, stop, and monitor Chrome instances
• Screenshot Capture: Take high-quality screenshots of web pages
• URL Navigation: Navigate to any website with automatic protocol handling
• JavaScript Execution: Execute custom JavaScript code in the browser context
• Process Management: Robust Chrome process lifecycle management
• Persistent Profiles: Chrome user data persistence during session

🛠️ Key Improvements Over Previous Version

Fixed Issues:

1. Gradio Schema Error: Resolved TypeError: argument of type 'bool' is not iterable by using proper Gradio component initialization
2. Launch Configuration: Fixed localhost accessibility issues with proper server configuration
3. Chrome Stability: Enhanced Chrome startup reliability with better error handling
4. Resource Management: Improved process cleanup and memory management

New Features:

1. JavaScript Console: Execute custom JavaScript code directly in the browser
2. Tabbed Interface: Organized functionality into logical tabs
3. Enhanced Status Monitoring: Real-time Chrome process status updates
4. Better Error Handling: Comprehensive error messages and recovery options
5. Optimized Performance: Reduced startup time and improved responsiveness

🏗️ Architecture

The application uses a class-based architecture with the ChromeController class managing:

• Chrome process lifecycle
• WebDriver connections
• Screenshot capture
• JavaScript execution
• Process monitoring

🐳 Docker Configuration

The Dockerfile is optimized for:

• Minimal image size with multi-stage optimization
• Proper Chrome dependencies installation
• Security best practices with non-root user
• Health checks for reliability

📋 Usage Instructions

1. Start Chrome: Click "🚀 Start Chrome" to launch the browser instance
2. Navigate: Enter a URL and click "🧭 Navigate" to visit websites
3. Screenshot: Use "📸 Take Screenshot" to capture the current page
4. Execute JS: Use the JavaScript tab to run custom code
5. Monitor: Check status and manage processes as needed

🔧 Technical Details

Chrome Arguments

Optimized Chrome flags for containerized environments:

• Headless mode with new engine
• Disabled GPU acceleration for CPU environments
• Security sandbox disabled for container compatibility
• Remote debugging enabled on port 9222
• Crash reporting disabled to prevent permission issues

Dependencies

• gradio==4.44.0 - Web interface framework
• selenium==4.25.0 - Browser automation
• webdriver-manager==4.0.2 - ChromeDriver management
• psutil==6.0.0 - Process management
• Pillow==10.4.0 - Image processing

🚨 Troubleshooting

Common Issues:

1. Chrome won't start

   • Check the status output for specific error messages
   • Ensure sufficient memory is available
   • Try stopping and restarting Chrome

2. Screenshots fail

   • Verify Chrome is running with "📊 Check Status"
   • Ensure the page has finished loading
   • Check if the target URL is accessible

3. JavaScript execution errors

   • Verify the JavaScript syntax
   • Ensure Chrome is running and has a page loaded
   • Check browser console for additional error details

Performance Tips:

• Keep Chrome running between operations for better performance
• Use the status check before taking screenshots
• Clean up processes periodically if running long sessions

🔒 Security Notes

• Runs in a sandboxed container environment
• Uses non-root user for enhanced security
• Chrome security features are partially disabled for container compatibility
• No persistent data storage outside the session

📝 License

MIT License - Feel free to use and modify as needed.

🤝 Contributing

This is an open-source project. Contributions, issues, and feature requests are welcome!

---

Built with ❤️ for the Hugging Face Spaces community