阿拉基斯

简介

AI智能体可能会生成恶意或存在漏洞的代码，从而攻击其运行的宿主系统。

许多智能体拥有复杂的多步计划来实现目标，并且能够回溯到中间状态以从中继续执行。

阿拉基斯提供了一个安全、完全可定制且自托管的解决方案，用于创建和管理用于代码执行及计算机使用的沙箱环境。它开箱即用地支持通过快照与恢复功能进行回溯。

• 设计上确保安全，每个沙箱都运行在微型虚拟机中。
• 每个沙箱启动时会运行Ubuntu系统，并内置代码执行服务和VNC服务器。
• 通过REST API、Python SDK py-arrakis以及一个MCP服务器，客户端（包括人类和AI智能体）可以编程方式创建沙箱、上传文件并在其中执行代码。
• 自动设置并管理从自托管公共服务器到运行在其上的沙箱的端口转发，即客户端无需额外配置即可轻松访问沙箱的图形界面（包括用于计算机操作的Chrome浏览器）。
• 开箱即用支持快照与恢复功能，这意味着AI智能体可以在完成部分工作后对沙箱进行快照保存，随后通过恢复快照回到之前的确切状态。这样，沙箱内任何已启动的进程、修改过的文件等都会被原样恢复。这对于基于蒙特卡洛树搜索的智能体或需要解释复杂执行流程的场景非常有用。

---

目录

• 简介
• 演示
• 设置
  • 先决条件
  • GCP设置
  • 使用预构建版本快速设置
  • 运行arrakis-restserver
  • 使用CLI或py-arrakis
• 快速入门
  • SDK
  • MCP
  • 用于计算机操作的GUI
  • CLI使用方法
• 架构与特性
• 定制化
• 贡献
  • 法律信息
    • 贡献者许可协议
    • 许可证
• 许可证

---

演示

观看Claude如何通过MCP利用阿拉基斯实时编写Google Docs克隆版。它甚至会对沙箱进行快照以记录进度。

---

设置

先决条件

• cloud-hypervisor仅在Linux机器上使用/dev/kvm进行虚拟化时才能正常工作。因此，我们仅支持Linux操作系统。
• 请通过以下命令检查主机是否已启用虚拟化：

  stat /dev/kvm
  

GCP设置

• 请按照GCP设置中的说明，在GCE虚拟机上设置阿拉基斯。

使用预构建版本快速设置

• 您可以利用我们的setup.sh脚本和预编译的二进制文件轻松设置阿拉基斯。

  curl -sSL https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh | bash
  ls arrakis-prebuilt
  

运行arrakis-restserver

• 现在我们已经有一个包含所有二进制文件和镜像的文件夹。我们需要首先运行arrakis-restserver。

  cd arrakis-prebuilt
  sudo ./arrakis-restserver
  

使用CLI或py-arrakis

• 您可以使用CLI或py-arrakis来创建和管理虚拟机。

  cd arrakis-prebuilt
  ./arrakis-client start -n agent-sandbox
  

---

快速入门

SDK

阿拉基斯附带一个Python SDK py-arrakis，使您能够无缝地创建、管理和与虚拟机交互。

• 安装SDK

    pip install py-arrakis
  

• 按照使用说明在Linux机器上运行arrakis-restserver，或者从官方发布页面下载预编译的二进制文件。

• 使用py-arrakis与arrakis-restserver交互。

• 运行不受信任的代码

  # 将此处替换为`arrakis-restserver`运行的IP地址和端口。
  sandbox_manager = SandboxManager('http://127.0.0.1:7000')
  
  # 启动一个新的沙箱。
  with sb as sandbox_manager.start_sandbox('agent-sandbox'):
    sb.run_cmd('echo hello world')
  
  # 当退出上下文时，沙箱`sb`会自动销毁。
  

• 对沙箱进行快照和恢复

  # 启动一个沙箱并向文件中写入一些数据。
  sandbox_name = 'agent-sandbox'
  sandbox = sandbox_manager.start_sandbox(sandbox_name)
  sandbox.run_cmd("echo 'test data before snapshot' > /tmp/testfile")
  snapshot_id = sandbox.snapshot("initial-state")
  sandbox.run_cmd("echo 'test data after snapshot' > /tmp/testfile")
  
  # 销毁沙箱。
  sandbox.destroy()
  
  # 从快照中恢复沙箱，并验证我们是否仍保留了快照时的数据。
  sandbox = sandbox_manager.restore(sandbox_name, snapshot_id)
  result = sandbox.run_cmd("cat /tmp/testfile")
  # result["output"]应为“test data before snapshot”。
  

---

MCP

• 阿拉基斯还配备了一个MCP服务器，允许Claude Desktop App、Windsurf、Cursor等MCP客户端创建和管理沙箱。
• 以下是一个claude_desktop_config.json示例：

  {
      "mcpServers": {
        "arrakis": {
            "command": "/Users/username/.local/bin/uv",
            "args": [
                "--directory",
                "/Users/username/Documents/projects/arrakis-mcp-server",
                "run",
                "arrakis_mcp_server.py"
            ]
        }
      }
  }
  

---

用于计算机的 GUI

• 每个沙箱在启动时都会运行一个 VNC 服务器。此外，它还预装了 Chrome 浏览器。

• Arrakis 还会处理端口转发，以便通过运行 arrakis-restserver 的开发服务器上的某个端口暴露 VNC 服务器。

• 启动一个沙箱，并获取关于该沙箱的元数据，包括 VNC 连接详情。

  # 将此处替换为运行 `arrakis-restserver` 的 IP:端口。
  sandbox_manager = SandboxManager('http://127.0.0.1:7000')
  sb = sandbox_manager.start_sandbox('agent-sandbox')
  print(sb.info())
  

• 我们可以从响应中的 port_forwards 字段获取 VNC 连接详情。VNC 服务器在端口转发条目中以描述 gui 表示。我们将使用 host_port 字段来连接到 VNC 服务器。

  {
    'name': 'agent-sandbox',
    'status': 'RUNNING',
    'ip': '10.20.1.2/24',
    'tap_device_name': 'tap0',
    'port_forwards': [{'host_port': '3000', 'guest_port': '5901', 'description': 'gui'}]
  }
  

• 使用任何 VNC 客户端 连接到 VNC 服务器以访问 GUI。

  # 我们可以看到端口 3000 是转发到沙箱内运行的 VNC 服务器的主机端口。
  ./utils/novnc_proxy --vnc <dev-server-ip>:3000
  

---

CLI 使用

• Arrakis 自带一个开箱即用的 CLI 客户端，可用于启动和管理虚拟机。

• 按照设置部分的说明启动 arrakis-restserver。

• 在另一个终端中，我们将使用 CLI 客户端来创建和管理虚拟机。

• 启动一个名为 foo 的虚拟机。它会返回有关该虚拟机的元数据，可用于与虚拟机交互。

  ./out/arrakis-client start -n foo
  

  已启动虚拟机：{"codeServerPort":"","ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
  

• 通过 SSH 登录到虚拟机。

  • SSH 凭据已在 这里 配置。

  # 使用返回的 IP 地址。密码为 "elara0000"
  ssh elara@10.20.1.2
  

• 检查名为 foo 的虚拟机。

  ./out/arrakis-client list -n foo
  

  虚拟机：{"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
  

• 列出所有虚拟机。

  ./out/arrakis-client list-all
  

  虚拟机：{"vms":[{"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}]}
  

• 停止虚拟机。

  ./out/arrakis-client stop -n foo
  

• 销毁虚拟机。

  ./out/arrakis-client destroy -n foo
  

• 虚拟机的快照与恢复。

  • 我们支持对虚拟机进行快照，然后使用该快照恢复虚拟机。目前，我们会将恢复后的虚拟机配置为与原始虚拟机相同的 IP 地址。如果计划在同一台主机上恢复虚拟机，请在恢复之前先停止或销毁原始虚拟机。未来这一限制将被解除。

  ./out/arrakis-client snapshot -n foo-original -o foo-snapshot
  

  ./out/arrakis-client destroy -n foo-original -o foo-snapshot
  

  ./out/arrakis-client restore -n foo-original --snapshot foo-snapshot
  

---

架构与特性

arrakis 包含以下服务和特性：

• REST API

  • arrakis-restserver
    • 一个守护进程，提供 REST API 用于启动、停止、销毁、列出所有虚拟机。每个启动的虚拟机都由该服务器管理，即每个虚拟机的生命周期与该守护进程的生命周期绑定。
    • API 文档位于 api/server-api.yaml。
    • 代码
  • arrakis-client
    • 一个 Golang 命令行工具，可用于与 arrakis-restserver 交互，从而启动和管理虚拟机。
    • 代码

• Python SDK

  • 查看官方 Python SDK - py-arrakis

• 安全性

  • 每个沙箱都在一个微型虚拟机中运行。
    • 微型虚拟机是轻量级的虚拟机（与传统虚拟机相比），由基于 Rust 的虚拟机管理程序驱动，例如 firecracker 和 cloud-hypervisor。
    • Arrakis 使用 cloud-hypervisor 作为虚拟机管理程序。
  • 沙箱内执行的任何不受信任的代码都与宿主机以及其他代理隔离。
  • 我们还使用 overlayfs 来保护每个沙箱的根文件系统。

• 定制化

  • 基于 Dockerfile 的根文件系统定制。
    • 通过修改 Dockerfile 可以轻松地向您的虚拟机根文件系统添加软件包和二进制文件。
  • 开箱即用的客户机网络设置。
    • 每个沙箱都会获得一个 tap 设备，并将其添加到宿主机上的 Linux 网桥中。
    • 提供对沙箱的 SSH 访问权限。
  • 沙箱的预构建 Linux 内核。
    • 或者在启动虚拟机时将您自己的内核传递给 arrakis-client。

---

定制化

• 详细 README 介绍了如何自定义沙箱中默认运行的软件包和二进制文件。

---

贡献

感谢您考虑为 arrakis 做出贡献！🎉

欢迎随时提交 PR。详细的贡献指南即将发布。

法律信息

贡献者许可协议

为了使我们能够接受来自您的补丁和其他贡献，您需要签署我们的 Arrakis 贡献者许可协议（简称“CLA”）。请发送邮件至 abshkbh@gmail.com 以开始此流程。

Arrakis 使用名为 CLA Assistant 的工具来跟踪贡献者的 CLA 状态。CLA Assistant 会在您的拉取请求中发表评论，表明您是否已签署 CLA。如果您尚未签署 CLA，则需要在我们接受您的贡献之前完成签署。签署 CLA 是一次性的过程，对您今后对 Arrakis 的所有贡献均有效，并且只需一分钟左右的时间，即可通过 GitHub 账户登录完成签署。

许可证

通过为 Arrakis 做出贡献，您同意您的贡献将根据 GNU Affero 通用公共许可证 v3.0 授权，并被视为商业软件。

---

许可证

本项目根据 GNU Affero 通用公共许可证 v3.0 授权。如需商业授权，请发送邮件至 abshkbh@gmail.com。

---

Arrakis 快速上手指南

Arrakis 是一个安全、可完全自定义且支持自托管的 AI 沙箱管理工具。它基于 MicroVM 技术，为 AI Agent 提供隔离的代码执行环境，并原生支持“快照与恢复”功能，便于 Agent 进行多步规划回溯。

环境准备

系统要求

• 操作系统：仅支持 Linux。
• 虚拟化支持：宿主机器必须开启虚拟化功能并拥有 /dev/kvm 设备。
  • 检查命令：

    stat /dev/kvm
    

  • 如果报错，请在 BIOS/UEFI 中开启 VT-x/AMD-V 支持。

前置依赖

• 确保已安装 curl 和 bash。
• 需要 sudo 权限以运行服务。

安装步骤

推荐使用官方提供的预构建脚本进行快速部署，该脚本会自动下载二进制文件和所需镜像。

1. 运行安装脚本

   curl -sSL https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh | bash
   

2. 验证安装 安装完成后，当前目录下会生成 arrakis-prebuilt 文件夹：

   ls arrakis-prebuilt
   

3. 启动 REST 服务 进入目录并启动核心服务（需 sudo 权限）：

   cd arrakis-prebuilt
   sudo ./arrakis-restserver
   

   保持该终端窗口运行，服务默认监听在 http://127.0.0.1:7000。

基本使用

你可以通过 Python SDK、CLI 命令行或 MCP 协议与 Arrakis 交互。以下展示最常用的两种方式。

方式一：使用 Python SDK (推荐)

适合集成到 AI Agent 代码中，支持上下文管理和自动资源清理。

1. 安装 SDK

   pip install py-arrakis
   

2. 运行示例代码 创建一个名为 agent-sandbox 的沙箱，执行命令并自动销毁：

   from py_arrakis import SandboxManager
   
   # 连接本地服务
   sandbox_manager = SandboxManager('http://127.0.0.1:7000')
   
   # 启动沙箱并执行命令 (上下文退出后自动销毁)
   with sandbox_manager.start_sandbox('agent-sandbox') as sb:
       result = sb.run_cmd('echo hello world')
       print(result)
   
   # 快照与恢复示例
   sandbox = sandbox_manager.start_sandbox('persistent-agent')
   sandbox.run_cmd("echo 'data_before' > /tmp/test.txt")
   
   # 创建快照
   snapshot_id = sandbox.snapshot("checkpoint-v1")
   
   # 修改数据
   sandbox.run_cmd("echo 'data_after' > /tmp/test.txt")
   
   # 销毁当前实例
   sandbox.destroy()
   
   # 从快照恢复，数据将回到 'data_before' 状态
   restored_sb = sandbox_manager.restore('persistent-agent', snapshot_id)
   print(restored_sb.run_cmd("cat /tmp/test.txt"))
   

方式二：使用 CLI 命令行

适合手动调试和管理虚拟机。

1. 启动沙箱 在新终端中进入安装目录：

   cd arrakis-prebuilt
   ./arrakis-client start -n my-sandbox
   

   输出将包含沙箱的 IP 地址（例如 10.20.1.2）。

2. SSH 连接 默认用户名为 elara，密码为 elara0000：

   ssh elara@<上面输出的 IP 地址>
   # 例如：ssh elara@10.20.1.2
   

3. 查看状态与管理

   # 查看特定沙箱信息
   ./arrakis-client list -n my-sandbox
   
   # 列出所有沙箱
   ./arrakis-client list-all
   
   # 创建快照
   ./arrakis-client snapshot -n my-sandbox -o my-snapshot
   
   # 停止沙箱
   ./arrakis-client stop -n my-sandbox
   
   # 彻底销毁沙箱
   ./arrakis-client destroy -n my-sandbox
   

访问图形界面 (GUI)

每个沙箱启动时都会运行 VNC 服务器并预装 Chrome 浏览器。

1. 调用 sb.info() (SDK) 或 list (CLI) 获取 port_forwards 信息。
2. 找到描述为 gui 的条目，记录其 host_port (例如 3000)。
3. 使用 VNC 客户端连接 <宿主机 IP>:<host_port> 即可看到桌面环境。