{"id":26937660,"url":"https://github.com/babelcloud/gru-sandbox","last_synced_at":"2025-04-02T13:15:48.100Z","repository":{"id":283245737,"uuid":"951033363","full_name":"babelcloud/gru-sandbox","owner":"babelcloud","description":"A self-hostable sandbox for MCP and AI agents.","archived":false,"fork":false,"pushed_at":"2025-03-28T01:02:15.000Z","size":175,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-28T02:21:32.827Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/babelcloud.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}},"created_at":"2025-03-19T04:07:56.000Z","updated_at":"2025-03-28T01:02:20.000Z","dependencies_parsed_at":"2025-03-19T12:46:39.863Z","dependency_job_id":null,"html_url":"https://github.com/babelcloud/gru-sandbox","commit_stats":null,"previous_names":["babelcloud/gru-sandbox"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babelcloud%2Fgru-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babelcloud%2Fgru-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babelcloud%2Fgru-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babelcloud%2Fgru-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/babelcloud","download_url":"https://codeload.github.com/babelcloud/gru-sandbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246819781,"owners_count":20839095,"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","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":[],"created_at":"2025-04-02T13:15:26.571Z","updated_at":"2025-04-02T13:15:48.090Z","avatar_url":"https://github.com/babelcloud.png","language":"Go","readme":"# gru-sandbox\n\nGru-sandbox(gbox) is an open source project that provides a self-hostable sandbox for MCP integration or other AI agent usecases.\n\nAs MCP is getting more and more popular, we find there is no easy way to enable MCP client such as Claude Desktop/Cursor to execute commands locally and securely. This project is based on the technology behind [gru.ai](https://gru.ai) and we wrap it into a system command and MCP server to make it easy to use.\n\nFor advanced scenarios, we also kept the ability to run sandboxes in k8s cluster locally or remotely.\n\n## Use Cases\n\nYour AI client such as Claude Desktop can use gbox MCP to deliver better results, such as\n\n### 1. Generating Diagrams\n\nGenerate diagrams of Tesla stock prices:\n![Image](https://i.imghippo.com/files/njBB6977VQQ.png)\nhttps://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a\n\n### 2. Generating PDFs\n\nGenerate PDF of latest AI news:\n![Image](https://i.imghippo.com/files/oMF9723LA.png)\nhttps://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a\n\n### 3. Analyzing and Calculation\n\nAnalyze and compare Nvidia/Tesla market cap:\n![Image](https://i.imghippo.com/files/FE2710WR.png)\nhttps://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994\n\n### 4. Processing Local Files (coming soon)\n\n```\nPlease compress all photos in shared folder and make sure each of them is smaller than 2MB.\n```\n\n### 5. Execute Arbitrary Tasks\n\nDownload youtube video:\n![Image](https://i.imghippo.com/files/TI9396Rjg.png)\nhttps://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9\n\n## Installation\n\n### System Requirements\n\n- macOS 10.15 or later\n- [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/)\n- [Homebrew](https://brew.sh)\n\n\u003e Note: Support for other platforms (Linux, Windows) is coming soon.\n\n### Installation Steps\n\n```bash\n# Install via Homebrew\nbrew tap babelcloud/gru \u0026\u0026 brew install gbox\n\n# Initialize environment\ngbox setup\n\n# Export MCP config and merge into Claude Desktop\ngbox mcp export --merge-to claude\n# or gbox mcp export --merge-to cursor\n\n# Restart Claude Desktop\n```\n\n### Update Steps\n\n```bash\n# Update gbox to the latest version\nbrew update \u0026\u0026 brew upgrade gbox\n\n# Update the environment\ngbox setup\n\n# Export and merge latest MCP config into Claude Desktop\ngbox mcp export --merge-to claude\n# or gbox mcp export --merge-to cursor\n\n# Restart Claude Desktop\n```\n\n## Command Line Usage\n\nThe project provides a command-line tool `gbox` for managing sandbox containers:\n\n```bash\n# Cluster management\ngbox cluster setup    # Setup cluster environment\ngbox cluster cleanup  # Cleanup cluster environment\n\n# Container management\ngbox box create --image python:3.9 --env \"DEBUG=true\" -w /app  # Create container\ngbox box list                                                  # List containers\ngbox box start \u003cbox-id\u003e                                        # Start container\ngbox box stop \u003cbox-id\u003e                                         # Stop container\ngbox box delete \u003cbox-id\u003e                                       # Delete container\ngbox box exec \u003cbox-id\u003e -- python -c \"print('Hello')\"           # Execute command\ngbox box inspect \u003cbox-id\u003e                                      # Inspect container\n\n# MCP configuration\ngbox mcp export                          # Export MCP configuration\ngbox mcp export --merge-to claude        # Export and merge into Claude Desktop config\ngbox mcp export --dry-run                # Preview merge result without applying changes\n```\n\n## Development Setup\n\n### Prerequisites\n\n- Go 1.21 or later\n- Docker Desktop\n- Make\n- pnpm (via corepack)\n- Node.js 16.13 or later\n\n### Build\n\n```bash\n# Build all components\nmake build\n\n# Create distribution package\nmake dist\n```\n\n### Running Services\n\n```bash\n# API Server\nmake -C packages/api-server dev\n\n# MCP Server\ncd packages/mcp-server \u0026\u0026 pnpm dev\n\n# MCP Inspector\ncd packages/mcp-server \u0026\u0026 pnpm inspect\n```\n\n## Contributing\n\nWe welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b username/feature-name`)\n3. Commit your changes (`git commit -m 'Add some feature'`)\n4. Push to the branch (`git push origin username/feature-name`)\n5. Open a Pull Request\n\n### Things to Know about Dev and Debug Locally\n\n#### How to run gbox in dev env instead of the system installed one\n\n1. Stop the installed gbox by `gbox cleanup`. It will stop the api server so that you can run the api server in dev env.\n2. Execute `make api-dev` in project root.\n3. Execute `./gbox box list`, this is the command run from your dev env.\n\n#### How to connect MCP client such as Claude Desktop to the MCP server in dev env\n\n1. Execute `make mcp-dev` in project root.\n2. Execute `./gbox mcp export --merge-to claude`\n\n#### How to open MCP inspect\n\n1. Execute `make mcp-inspect` in project root.\n2. Click the link returned in terminal.\n\n#### How to build and use image in dev env\n\n1. Execute `make build-image-python` in project root to build Python image, or `make build-images` to build all images.\n2. Change the image name as needed (e.g., `make build-image-typescript` for TypeScript image).\n3. You may need to delete current sandboxes to make the new image effective `./gbox box delete --all`\n\n#### Why MCP client still get the old MCP content?\n\n1. After you change MCP configuration such as tool definitions, you need to run `make build` to update the `dist/index.js` file.\n2. You may also need to execute `./gbox mcp export --merge-to claude`\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":["Table of Contents","📦 Other","Community Servers"],"sub_categories":["Other Tools and Integrations"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabelcloud%2Fgru-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbabelcloud%2Fgru-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabelcloud%2Fgru-sandbox/lists"}