gbox
gbox is an open source project that provides a self-hostable sandbox for MCP integration or other AI agent usecases. The sandbox can be used as a computer for agent. It includes all necessary tools that agents needs for daily tasks, such as terminal, browser and file editor. See "Features" section for details,
As MCP is getting more and more popular, we find there is no easy way to enable MCP client such as Claude Desktop/Cursor to run tasks locally and securely. This project is based on the technology behind gru.ai and we wrap it into a system command and MCP server to make it easy to use.
For advanced scenarios, we also kept the ability to run sandboxes in k8s cluster locally or remotely.
Features
- Terminal
- File
- Browser
- HTTP Server
- SDKs
- MCP
Use Cases
Your AI client such as Claude Desktop can use gbox MCP to deliver better results, such as
1. Generating Diagrams
Generate diagrams of Tesla stock prices:
Image
https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a
2. Generating PDFs
Generate PDF of latest AI news:
Image
https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a
3. Analyzing and Calculation
Analyze and compare Nvidia/Tesla market cap:
Image
https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994
4. Processing Local Files
Find images in download folder and compress into zip.
image
https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42
5. Execute Arbitrary Tasks
Download youtube video:
Image
https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9
Installation
System Requirements
- macOS 10.15 or later
Note: Support for other platforms (Linux, Windows) is coming soon.
Installation Steps
Update Steps
Command Line Usage
The project provides a command-line tool
gbox for managing sandbox containers:Volume Mounts
The
gbox box create command supports Docker-compatible volume mounts using the -v or --volume flag. This allows you to share files and directories between your host system and the sandbox containers.The volume mount syntax follows this format:
Where:
/host/path: Path to a file or directory on your host system
/container/path: Path where the file or directory will be mounted in the container
ro(optional): Makes the mount read-only
propagation(optional): Sets the mount propagation mode (private, rprivate, shared, rshared, slave, rslave)
Examples:
Note: The host path must exist before creating the container. The container path will be created automatically if it doesn't exist.
Development Setup
Prerequisites
- Go 1.21 or later
- Docker Desktop
- Make
- pnpm (via corepack)
- Node.js 16.13 or later
Build
Running Services
Contributing
We 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.
- Fork the repository
- Create your feature branch (
git checkout -b username/feature-name)
- Commit your changes (
git commit -m 'Add some feature')
- Push to the branch (
git push origin username/feature-name)
- Open a Pull Request
Things to Know about Dev and Debug Locally
How to run gbox in dev env instead of the system installed one
- Stop the installed gbox by
gbox cleanup. It will stop the api server so that you can run the api server in dev env.
- Execute
make api-devin project root.
- Execute
./gbox box list, this is the command run from your dev env.
How to connect MCP client such as Claude Desktop to the MCP server in dev env
- Execute
make mcp-devin project root.
- Execute
./gbox mcp export --merge-to claude
How to open MCP inspect
- Execute
make mcp-inspectin project root.
- Click the link returned in terminal.
How to build and use image in dev env
- Execute
make build-image-pythonin project root to build Python image, ormake build-imagesto build all images.
- Change the image name as needed (e.g.,
make build-image-typescriptfor TypeScript image).
- You may need to delete current sandboxes to make the new image effective
./gbox box delete --all
Why MCP client still get the old MCP content?
- After you change MCP configuration such as tool definitions, you need to run
make buildto update thedist/index.jsfile.
- You may also need to execute
./gbox mcp export --merge-to claude
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
gbox
gbox is an open source project that provides a self-hostable sandbox for MCP integration or other AI agent usecases. The sandbox can be used as a computer for agent. It includes all necessary tools that agents needs for daily tasks, such as terminal, browser and file editor. See "Features" section for details,
As MCP is getting more and more popular, we find there is no easy way to enable MCP client such as Claude Desktop/Cursor to run tasks locally and securely. This project is based on the technology behind gru.ai and we wrap it into a system command and MCP server to make it easy to use.
For advanced scenarios, we also kept the ability to run sandboxes in k8s cluster locally or remotely.
Features
- Terminal
- File
- Browser
- HTTP Server
- SDKs
- MCP
Use Cases
Your AI client such as Claude Desktop can use gbox MCP to deliver better results, such as
1. Generating Diagrams
Generate diagrams of Tesla stock prices:
Image
https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a
2. Generating PDFs
Generate PDF of latest AI news:
Image
https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a
3. Analyzing and Calculation
Analyze and compare Nvidia/Tesla market cap:
Image
https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994
4. Processing Local Files
Find images in download folder and compress into zip.
image
https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42
5. Execute Arbitrary Tasks
Download youtube video:
Image
https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9
Installation
System Requirements
- macOS 10.15 or later
Note: Support for other platforms (Linux, Windows) is coming soon.
Installation Steps
Update Steps
Command Line Usage
The project provides a command-line tool
gbox for managing sandbox containers:Volume Mounts
The
gbox box create command supports Docker-compatible volume mounts using the -v or --volume flag. This allows you to share files and directories between your host system and the sandbox containers.The volume mount syntax follows this format:
Where:
/host/path: Path to a file or directory on your host system
/container/path: Path where the file or directory will be mounted in the container
ro(optional): Makes the mount read-only
propagation(optional): Sets the mount propagation mode (private, rprivate, shared, rshared, slave, rslave)
Examples:
Note: The host path must exist before creating the container. The container path will be created automatically if it doesn't exist.
Development Setup
Prerequisites
- Go 1.21 or later
- Docker Desktop
- Make
- pnpm (via corepack)
- Node.js 16.13 or later
Build
Running Services
Contributing
We 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.
- Fork the repository
- Create your feature branch (
git checkout -b username/feature-name)
- Commit your changes (
git commit -m 'Add some feature')
- Push to the branch (
git push origin username/feature-name)
- Open a Pull Request
Things to Know about Dev and Debug Locally
How to run gbox in dev env instead of the system installed one
- Stop the installed gbox by
gbox cleanup. It will stop the api server so that you can run the api server in dev env.
- Execute
make api-devin project root.
- Execute
./gbox box list, this is the command run from your dev env.
How to connect MCP client such as Claude Desktop to the MCP server in dev env
- Execute
make mcp-devin project root.
- Execute
./gbox mcp export --merge-to claude
How to open MCP inspect
- Execute
make mcp-inspectin project root.
- Click the link returned in terminal.
How to build and use image in dev env
- Execute
make build-image-pythonin project root to build Python image, ormake build-imagesto build all images.
- Change the image name as needed (e.g.,
make build-image-typescriptfor TypeScript image).
- You may need to delete current sandboxes to make the new image effective
./gbox box delete --all
Why MCP client still get the old MCP content?
- After you change MCP configuration such as tool definitions, you need to run
make buildto update thedist/index.jsfile.
- You may also need to execute
./gbox mcp export --merge-to claude
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.