Skip to main content
Glama
Sign In
deenesjakoruzh

gbox

by babelcloud
GitHub
Go
Apache 2.0
25
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Provides a sandboxed Python environment for executing code and scripts.

  • Offers a sandboxed TypeScript environment for code execution.

  • Enables downloading YouTube videos through the MCP server integration.

gbox

gbox is an open source project that provides a self-hostable sandbox for Agents to execute commands, read/write files, browse the web, operate iOS/Android. The sandbox can be used as a computer/phone/pad for agent. See "Features" section for details.

This project is based on the technology behind gru.ai. It has been tested over 100000 Agent jobs.

For advanced scenarios, we also kept the ability to run sandboxes in k8s cluster locally or remotely.

As MCP is getting more and more popular, we also implemented a MCP server to make it easy to be directly integrated into MCP client such as Claude Desktop/Cursor.

Features

  1. Terminal
    • Execute any linux command
    • Execute python scripts directly
    • Share session across invokes [under-development]
  2. File
    • Mount host machine folders into sandbox
    • Access sandbox files through http links
    • Read file content in multi-modal
    • Write/re-write files
    • Edit files [under-development]
    • Search files [under-development]
  3. Browser
    • Open any url, return content in multi-modal
    • Download from any url [under-development]
    • Operate browser by instructions [under-development]
    • Human take over [under-development]
  4. HTTP Server
    • Start http service on any folder on demand [under-development]
  5. SDKs
    • Python SDK: Install using pip install pygbox. See PyPI for details.
    • Typescript SDK
  6. MCP
    • Standard MCP support
    • Integrate Claude Desktop & Cursor

Use gbox as a SDK

Python SDK

pip install pygbox

Python SDK Documentation

Typescript SDK

npm install @gru/gbox

Typescript SDK Documentation

Use gbox as a CLI

Installation

System Requirements

Note: Support for other platforms (Linux, Windows) is coming soon.

Installation Steps

# Install via Homebrew brew tap babelcloud/gru && brew install gbox # Initialize environment gbox setup # Export MCP config and merge into Claude Desktop gbox mcp export --merge-to claude # or gbox mcp export --merge-to cursor # Restart Claude Desktop

Update Steps

# Update gbox to the latest version brew update && brew upgrade gbox # Update the environment gbox setup # Export and merge latest MCP config into Claude Desktop gbox mcp export --merge-to claude # or gbox mcp export --merge-to cursor # Restart Claude Desktop

Command Line Usage

The project provides a command-line tool gbox for managing sandbox containers:

# Cluster management gbox cluster setup # Setup cluster environment gbox cluster cleanup # Cleanup cluster environment # Container management gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app # Create container gbox box list # List containers gbox box start <box-id> # Start container gbox box stop <box-id> # Stop container gbox box delete <box-id> # Delete container gbox box exec <box-id> -- python -c "print('Hello')" # Execute command gbox box inspect <box-id> # Inspect container # MCP configuration gbox mcp export # Export MCP configuration gbox mcp export --merge-to claude # Export and merge into Claude Desktop config gbox mcp export --dry-run # Preview merge result without applying changes

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:

-v /host/path:/container/path[:ro][:propagation]

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:

# Basic bind mount gbox box create -v /data:/data --image python:3.9 # Read-only bind mount gbox box create -v /data:/data:ro # Multiple bind mounts gbox box create \ -v /config:/etc/myapp \ -v /data:/var/lib/myapp:ro \ -v /logs:/var/log/myapp:ro:rprivate \ --image python:3.9

Note: The host path must exist before creating the container. The container path will be created automatically if it doesn't exist.

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: https://claude.ai/share/34de8ca3-4e04-441b-9e79-5875fa9fc97a

2. Generating PDFs

Generate PDF of latest AI news: https://claude.ai/share/84600933-dcf2-44be-a2fd-7f49540db57a

3. Analyzing and Calculation

Analyze and compare Nvidia/Tesla market cap: https://claude.ai/share/70c335b7-9fff-4ee7-8459-e6b7462d8994

4. Processing Local Files

Find images in download folder and compress into zip. https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42

5. Execute Arbitrary Tasks

Download youtube video: https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9

Develop gbox

Prerequisites

  • Go 1.21 or later
  • Docker Desktop
  • Make
  • pnpm (via corepack)
  • Node.js 16.13 or later

Build

# Build all components make build # Create distribution package make dist

Running Services

# API Server make -C packages/api-server dev # MCP Server cd packages/mcp-server && pnpm dev # MCP Inspector cd packages/mcp-server && pnpm inspect

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.

  1. Fork the repository
  2. Create your feature branch (git checkout -b username/feature-name)
  3. Commit your changes (git commit -m 'Add some feature')
  4. Push to the branch (git push origin username/feature-name)
  5. 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
  1. Stop the installed gbox by gbox cleanup. It will stop the api server so that you can run the api server in dev env.
  2. Execute make api-dev in project root.
  3. 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
  1. Execute make mcp-dev in project root.
  2. Execute ./gbox mcp export --merge-to claude
How to open MCP inspect
  1. Execute make mcp-inspect in project root.
  2. Click the link returned in terminal.
How to build and use image in dev env
  1. Execute make build-image-python in project root to build Python image, or make build-images to build all images.
  2. Change the image name as needed (e.g., make build-image-typescript for TypeScript image).
  3. 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?
  1. After you change MCP configuration such as tool definitions, you need to run make build to update the dist/index.js file.
  2. 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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Gru-sandbox(gbox) is an open source project that provides a self-hostable sandbox for MCP integration or other AI agent usecases.

  1. Features
    1. Use gbox as a SDK
      1. Python SDK
      2. Typescript SDK
    2. Use gbox as a CLI
      1. Installation
        1. System Requirements
        2. Installation Steps
        3. Update Steps
        4. Command Line Usage
        5. Volume Mounts
      2. MCP Use Cases
        1. 1. Generating Diagrams
        2. 2. Generating PDFs
        3. 3. Analyzing and Calculation
        4. 4. Processing Local Files
        5. 5. Execute Arbitrary Tasks
      3. Develop gbox
        1. Prerequisites
        2. Build
        3. Running Services
        4. Contributing
        5. Things to Know about Dev and Debug Locally
      4. License

        Related MCP Servers

        • MCP-toolhouse

          SecretiveShell
          -
          security
          A
          license
          -
          quality
          MCP server for toolhouse.ai. This does not rely on an external llm unlike the official server.
          Last updated -
          1
          Python
          MIT License

        • Container-MCP

          54rt1n
          -
          security
          A
          license
          -
          quality
          A secure, container-based implementation of the Model Context Protocol (MCP) that provides sandboxed environments for AI systems to safely execute code, run commands, access files, and perform web operations.
          Last updated -
          4
          Python
          Apache 2.0
          • Linux

        • MCP-ShellJS

          erniebrodeur
          -
          security
          F
          license
          -
          quality
          A secure MCP server that provides controlled ShellJS access for LLMs, enabling AI systems to safely execute shell commands and interact with the filesystem within a configurable security sandbox.
          Last updated -
          JavaScript

        View all related MCP servers

        Appeared in Searches

        New MCP Servers

        ID: 1hy7nhkq3s