使用说明

项目简介

microsandbox 是一个用于安全执行不受信任代码（例如 AI 生成或用户提交的代码）的平台。它利用轻量级虚拟机 (microVMs) 提供强大的隔离性，同时保持极快的启动速度。microsandbox 服务器模块是一个 MCP 服务器实现，允许 LLM 客户端以标准化的方式访问其沙箱功能。

主要功能点

安全隔离: 通过硬件级别的 microVM 提供强大的隔离环境，确保代码执行不影响宿主系统。
快速启动: 沙箱（MicroVM）启动时间通常在 200ms 以下，响应迅速。
AI 就绪: 内置 Model Context Protocol (MCP) 支持，与 MCP 兼容的 AI 工具和 Agent 可以无缝集成，调用沙箱功能。
代码/命令执行: 允许在隔离的沙箱内执行指定语言（如 Python, Node.js）的代码或 shell 命令。
资源管理: 管理沙箱的生命周期（启动、停止）和配置（使用指定的 Docker 镜像、限制内存、CPU 等）。
状态持久化: 支持在项目模式下运行的沙箱状态持久化，方便开发和调试。
多语言 SDK: 提供多种主流编程语言（Python, JavaScript, Rust 等）的客户端开发工具包，简化与服务器的交互。

安装步骤

microsandbox 提供了一个简单的安装脚本，可以轻松安装包括服务器和 portal 在内的 CLI 工具：

curl -sSL https://get.microsandbox.dev | sh

这将下载并安装 'msb' CLI 工具到您的系统中。

服务器配置 (供 MCP 客户端使用)

microsandbox 服务器作为 MCP 服务器运行，并支持 MCP 客户端通过 JSON-RPC 协议与 '/mcp' 路径进行通信。

MCP 客户端通常需要配置如何启动或连接到 MCP 服务器。典型的配置信息需要提供服务器可执行文件的路径及其启动参数。

对于 microsandbox 服务器，其主要的可执行文件是 'msbserver'。您可以通过在终端运行 'which msbserver' 来查找其具体路径。

基本的服务器启动命令是 'msb server start'。在非开发模式下，为了安全起见，服务器需要一个密钥。您可以提供 '--key' 参数，或者如果密钥文件（位于 microsandbox 家目录）已存在，服务器将自动使用它。在开发模式下（通过 '--dev' 参数启用），服务器无需密钥即可运行，方便测试和开发。

以下是 MCP 客户端配置所需信息的示例说明（请注意，这仅描述需要提供的信息，具体的配置格式取决于您使用的 MCP 客户端）：

服务器名称 (server name): 例如 "Microsandbox MCP Server"
可执行命令路径 (command): '/path/to/your/msbserver' (请替换为实际路径)
命令参数 (args): '["server", "start", "--dev"]' (根据需要调整，例如移除 '--dev' 并在其他地方配置密钥)
MCP 路径 (capabilities.json_rpc.path): '/mcp' (MCP 请求通过此路径发送)

根据您的需求，您可能还需要提供 '--host <主机地址>' 和 '--port <端口>' 参数给 'msbserver start' 命令，以指定服务器监听的网络地址和端口。

基本使用方法

启动 microsandbox 服务器: 打开终端，运行以下命令（这里以开发模式为例）：
```
msb server start --dev
```
服务器将启动并监听配置的地址（默认为 '127.0.0.1:5555'）。
连接 MCP 客户端: 一旦服务器运行，任何支持 MCP 协议的 LLM 客户端或 Agent 都可以配置连接到该服务器。通常，客户端会连接到服务器的监听地址和端口，并使用 '/mcp' 路径发送 MCP JSON-RPC 请求。

使用 SDK (面向开发者): 如果您是开发者，您可以使用 microsandbox 提供的多种语言 SDK 与服务器交互，而无需直接构建 MCP 或 JSON-RPC 请求。SDK 提供了更友好的编程接口来启动沙箱、执行代码/命令和获取状态。

例如，使用 Python SDK 启动沙箱并执行 Python 代码：

import asyncio
from microsandbox import PythonSandbox

async def main():
    # 使用上下文管理器自动管理沙箱生命周期 (启动和停止)
    async with PythonSandbox.create(name="my-python-sandbox") as sb:
        # 在沙箱中执行 Python 代码
        exec = await sb.run("print('Hello from sandbox!')")
        # 获取并打印执行结果的标准输出
        print(await exec.output())

# 运行异步主函数
asyncio.run(main())

这段 Python 代码将通过 SDK 连接到运行中的 microsandbox 服务器，请求启动一个 Python 沙箱，执行指定的打印语句，然后获取输出并停止沙箱。

更多详细的使用方法和 SDK 示例，请参考项目的官方文档和 SDK 目录下的示例代码。

关键词