{"id":25461094,"url":"https://github.com/venopyx/isolator","last_synced_at":"2026-04-13T21:31:37.586Z","repository":{"id":278083062,"uuid":"934455107","full_name":"venopyX/isolator","owner":"venopyX","description":"Powerful and flexible application isolation tool for Linux that uses bubblewrap to create secure, isolated environments for running applications. It provides enhanced security features, GUI application support, and configurable isolation levels.","archived":false,"fork":false,"pushed_at":"2025-02-18T02:13:28.000Z","size":41,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T03:34:57.707Z","etag":null,"topics":["bubblewrap","docker","docker-container","environment","gui","gui-docker","isolator","linux","open-source","podman","pypi","python","security","temporal-data"],"latest_commit_sha":null,"homepage":"","language":"Python","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/venopyX.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}},"created_at":"2025-02-17T21:34:19.000Z","updated_at":"2025-02-18T02:13:31.000Z","dependencies_parsed_at":"2025-05-17T04:08:36.726Z","dependency_job_id":"476e0144-092b-426e-a4d0-ce89afecad56","html_url":"https://github.com/venopyX/isolator","commit_stats":null,"previous_names":["venopyx/isolator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/venopyX/isolator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venopyX%2Fisolator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venopyX%2Fisolator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venopyX%2Fisolator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venopyX%2Fisolator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/venopyX","download_url":"https://codeload.github.com/venopyX/isolator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venopyX%2Fisolator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019319,"owners_count":26086711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bubblewrap","docker","docker-container","environment","gui","gui-docker","isolator","linux","open-source","podman","pypi","python","security","temporal-data"],"created_at":"2025-02-18T05:22:30.219Z","updated_at":"2025-10-14T15:35:05.795Z","avatar_url":"https://github.com/venopyX.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Isolator\n\n[![PyPI version](https://badge.fury.io/py/isolator.svg)](https://badge.fury.io/py/isolator)\n[![Python](https://img.shields.io/pypi/pyversions/isolator.svg)](https://pypi.org/project/isolator/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA powerful and flexible application isolation tool for Linux that uses bubblewrap to create secure, isolated environments for running applications. Isolator provides enhanced security features, GUI application support, and configurable isolation levels.\n\n## Features\n\n- 🔒 Enhanced security with customizable seccomp profiles\n- 🖥️ Full GUI application support (X11 and Wayland)\n- 📁 Advanced filesystem isolation with overlay support\n- 🛡️ Multiple security levels with fine-grained controls\n- 🎮 YAML-based application profiles\n- 📊 Resource monitoring and limits\n- 🔍 Comprehensive logging and debugging\n- ⚡ Performance optimization with cgroup support\n- 🛠️ Flexible configuration system\n\n## Requirements\n\n- Python 3.8 or higher\n- Linux operating system\n- bubblewrap package installed (`sudo apt install bubblewrap` OR `sudo apt install bwrap` on Debian/Ubuntu)\n\n## Installation\n\n### From PyPI\n\n```bash\npip install isolator\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/venopyx/isolator.git\ncd isolator\npip install -e .\n```\n\n\u003e NOTE: If you're using Kali Linux, consider using `pipx` inplace of `pip`.\n\n\n## Basic Usage\n\n### Simple Application Launch\n\nRun any application in an isolated environment:\n\n```bash\n# Run Firefox in isolation\nisolator firefox\n\n# Run VS Code in isolation\nisolator code\n\n# Run VLC media player in isolation\nisolator vlc\n```\n\n### Command Arguments\n\nYou can pass arguments to the isolated application:\n\n```bash\n# Open a specific URL in Firefox\nisolator -- firefox https://github.com\n\n# Open a file in VS Code\nisolator -- code myproject/\n\n# Play a specific file in VLC\nisolator -- vlc myvideo.mp4\n```\n\n\u003e Use `--` to pass arguments to the isolated application, so it's not treated as a flag by `isolator`.\n\n## Advanced Options\n\n### Isolation Levels\n\n```bash\n# Run with minimal isolation\nisolator --isolation-level minimal firefox\n\n# Run with standard isolation (default)\nisolator --isolation-level standard firefox\n\n# Run with strict isolation\nisolator --isolation-level strict firefox\n```\n\nEach isolation level provides different security features:\n- `minimal`: Basic process and filesystem isolation\n- `standard`: Adds display server isolation and basic security features\n- `strict`: Maximum isolation including network restrictions and enhanced seccomp filtering\n\n### Resource Limits\n\n```bash\n# Run with memory limit\nisolator --memory 2G firefox\n\n# Run with CPU limit\nisolator --cpu 50 firefox\n\n# Run with combined limits\nisolator --memory 2G --cpu 50 --io-weight 100 firefox\n```\n\n### Custom Profiles\n\nCreate custom YAML profiles in `~/.config/isolator/profiles/`:\n\n```yaml\nname: CUSTOM_BROWSER\nmounts:\n  - /usr/share/fonts\n  - /usr/share/chrome\ndevices:\n  - /dev/dri\ncapabilities:\n  - CAP_SYS_ADMIN\nresource_limits:\n  memory_limit: \"2G\"\n  cpu_limit: 50\n```\n\nThen use your custom profile:\n\n```bash\nisolator --profile CUSTOM_BROWSER chrome\n```\n\n\u003c!-- \u003e #### Strict Isolation Note\n\u003e When using `--isolation-level strict` with GUI applications, ensure your X11/Wayland server is configured to allow connections from isolated environments. This may require setting up X authority permissions or adjusting Wayland socket access. --\u003e\n\n### Application Profiles\n\n```bash\n# Explicitly set browser profile\nisolator --profile BROWSER chrome\n\n# Use multimedia profile for media applications\nisolator --profile MULTIMEDIA vlc\n\n# Development profile for IDEs and tools\nisolator --profile DEVELOPMENT code\n```\n\nAvailable profiles:\n- `BASIC`: Default profile for general applications\n- `BROWSER`: Optimized for web browsers\n- `MULTIMEDIA`: Configured for media applications\n- `DEVELOPMENT`: Tailored for development tools\n- `GRAPHICS`: Optimized for graphics applications\n\n### Persistent Storage\n\n```bash\n# Run with persistent storage\nisolator --persist ~/my-isolated-data firefox\n\n# Run with persistent storage and strict isolation\nisolator --persist ~/my-isolated-data --isolation-level strict firefox\n```\n\n### Network Control\n\n```bash\n# Run without network access\nisolator --no-network firefox\n\n# Run with network access (default)\nisolator firefox\n```\n\n### GUI Support\n\n```bash\n# Run without GUI support\nisolator --no-gui application\n\n# Run with GUI support (default)\nisolator application\n```\n\n### Debug Logging\n\n```bash\n# Enable debug logging\nisolator --debug firefox\n```\n\n## Environment Variables\n\nIsolator respects and manages various environment variables:\n\n```bash\n# Set custom temporary directory\nexport ISOLATOR_TMP_DIR=/path/to/tmp\nisolator firefox\n\n# Set custom XDG runtime directory\nexport XDG_RUNTIME_DIR=/run/user/1000\nisolator firefox\n```\n\n## Security Considerations\n\nIsolator provides several security features:\n\n1. **Filesystem Isolation**:\n   - Read-only system directories\n   - Isolated home directory\n   - Temporary writable storage\n\n2. **Process Isolation**:\n   - Separate PID namespace\n   - IPC isolation\n   - User namespace isolation (in strict mode)\n\n3. **Network Isolation**:\n   - Optional network access\n   - Configurable network restrictions\n\n4. **Display Server Isolation**:\n   - Secure X11/Wayland access\n   - Protected cookie handling\n\n## Examples\n\n### Web Browser Isolation\n\n```bash\n# Run Chrome with persistent profile\nisolator --persist ~/.chrome-isolated \\\n         --profile BROWSER \\\n         google-chrome\n\n# Run Firefox in strict mode\nisolator --isolation-level strict \\\n         --profile BROWSER \\\n         firefox\n```\n\n### Development Environment\n\n```bash\n# Run VS Code with custom storage\nisolator --persist ~/.vscode-isolated \\\n         --profile DEVELOPMENT \\\n         code myproject/\n\n# Run PyCharm with debug logging\nisolator --debug \\\n         --profile DEVELOPMENT \\\n         --persist ~/.pycharm-isolated \\\n         pycharm\n```\n\n### Multimedia Applications\n\n```bash\n# Run VLC with multimedia profile\nisolator --profile MULTIMEDIA \\\n         --persist ~/.vlc-isolated \\\n         vlc\n\n# Run OBS Studio with network access\nisolator --profile MULTIMEDIA \\\n         --persist ~/.obs-isolated \\\n         obs\n```\n\n## Configuration File\n\nIsolator supports configuration files for persistent settings:\n\n```ini\n# ~/.config/isolator/config.ini\n[default]\nisolation_level = standard\npersist_dir = ~/.isolated-data\nnetwork_enabled = true\ngui_enabled = true\ndebug = false\n\n[browser]\nprofile = browser\npersist_dir = ~/.browser-isolated\n\n[development]\nprofile = development\npersist_dir = ~/.dev-isolated\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Application fails to start**:\n   ```bash\n   # Check with debug logging\n   isolator --debug application\n   ```\n\n2. **Display issues**:\n   ```bash\n   # Verify X11 socket access\n   isolator --debug --profile BROWSER firefox\n   ```\n\n3. **Network problems**:\n   ```bash\n   # Test network connectivity\n   isolator --debug application\n   ```\n\n### Debug Information\n\nEnable detailed logging for troubleshooting:\n\n```bash\nisolator --debug application 2\u003e debug.log\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Contact\n\nGemechis Chala - gladsonchala@gmail.com\n\nProject Link: [https://github.com/venopyx/isolator](https://github.com/venopyx/isolator)\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenopyx%2Fisolator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvenopyx%2Fisolator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenopyx%2Fisolator/lists"}