EdgeBox

EdgeBox exposes its capabilities through the MCP (Model Context Protocol) API, providing both a full GUI desktop environment and a command-line shell for AI agents. This server lets an LLM agent perform real-world desktop interactions, including programmatically controlling applications, executing code in isolated sandboxes, and managing files, all through MCP tools. When GUI tools are enabled, agents can interact with a local desktop via a VNC session, launch and use applications like a browser and code editor, and visually perceive the desktop state via screenshots. The MCP surface is organized into Core Tools (CLI mode, always available) for code execution, shell access, and filesystem operations, plus Desktop Tools (GUI mode) for mouse, keyboard, window, and visual control tasks. Agents connect using MCP-compatible clients and can manage multiple isolated sessions using the x-session-id header.

Prerequisites

• A supported runtime for EdgeBox (as the MCP server, typically Node.js for this build).
• Git and network access to clone the repository and install dependencies.
• Optional: Docker if you prefer containerized execution.

Installation steps

1. Clone the repository: git clone https://github.com/BIGPPWONG/EdgeBox.git cd EdgeBox

2. Install dependencies (Node.js project): npm install

3. Configure runtime options (optional):

   • Create or edit a config.json to adjust paths, ports, and environment variables.
   • Example: { "port": 8080, "guiEnabled": true, "logLevel": "info" }

4. Run the MCP server: npm run start

5. Verify the MCP endpoint is reachable (e.g., http://localhost:8080/mcp): curl http://localhost:8080/mcp/health

If you prefer Docker, you can adapt the following pattern after building an image named edgebox:

6. Docker (alternative): docker run -p 8080:8080 edgebox:latest

Prerequisites recap

• Node.js (or Docker) installed on the host
• Network access for dependencies and assets
• Basic familiarity with MCP clients and session headers

Tips and notes:

• GUI Tools require the GUI subsystem to be available; enable guiEnabled in your config if you want desktop interactions via VNC.
• Each MCP session is isolated; use the x-session-id header to manage multiple concurrent sandboxes.
• For security, run EdgeBox on a trusted machine and consider network isolation if exposing MCP endpoints externally.
• If you encounter permission issues with desktop automation, ensure the host user has appropriate rights to simulate input and capture screenshots.
• Environment variables like EDGEBOX_CONFIG and EDGEBOX_LOG_LEVEL can help customize behavior without editing code.
• When debugging, check logs at the configured log level to trace MCP tool invocations and session management.