Arrakis

서론 (Introduction)

AI 에이전트 (AI agents)는 실행 중인 호스트 시스템을 공격할 수 있는 악성 코드나 버그가 있는 코드를 생성할 수 있습니다.

많은 에이전트들은 목표를 달성하기 위해 정교한 다단계 계획을 세우며, 중간 상태로 되돌아가는 (backtrack) 능력을 통해 이득을 얻습니다.

Arrakis는 코드 실행 및 컴퓨터 사용을 위한 샌드박스 (Sandboxes)를 생성하고 관리할 수 있는 보안성, 완전한 커스터마이징 가능성, 그리고 셀프 호스팅 (self-hosted) 가능한 솔루션을 제공합니다. 이 서비스는 **스냅샷 및 복구 (snapshot-and-restore)**를 통한 되돌리기 (backtracking) 기능을 기본적으로 지원합니다.

• 설계 단계부터 보안을 고려하여, 각 샌드박스는 MicroVM 내에서 실행됩니다.

• 각 샌드박스는 내부에서 Ubuntu를 실행하며, 부팅 시 코드 실행 서비스와 VNC 서버가 작동합니다.

• REST API, Python SDK인 py-arrakis, 그리고 MCP 서버를 통해 클라이언트(인간 및 AI 에이전트 모두)가 프로그래밍 방식으로 샌드박스를 생성하고, 파일을 업로드하며, 각 샌드박스 내부에서 코드를 실행할 수 있습니다.

• 셀프 호스팅되는 퍼블릭 서버에서 실행 중인 샌드박스로의 포트 포워딩 (port forwarding)을 자동으로 설정하고 관리합니다. 즉, 클라이언트는 추가 설정 없이도 샌드박스 GUI(컴퓨터 사용을 위한 Chrome 포함)에 쉽게 접근할 수 있습니다.

• **스냅샷 및 복구 (snapshot-and-restore)**를 기본적으로 지원합니다. 즉, AI 에이전트가 작업을 수행한 후 샌드박스를 스냅샷으로 찍고, 나중에 스냅샷을 복구함으로써 정확히 이전 상태로 되돌아갈 수 있습니다. 이는 생성된 모든 프로세스, 수정된 파일 등이 샌드박스 내부에서 그대로 복구됨을 의미합니다. 이는 몬테카를로 트리 탐색 (Monte Carlo Tree Search) 기반 에이전트나 정교한 에이전트 실행 흐름의 설명 가능성 (explainability)을 확보하는 데 유용합니다.

목차 (Table of Contents)

목차 (Table of Contents)

• 서론 (Introduction)
• 데모 (Demo)
• 설정 (Setup)
  • 사전 요구 사항 (Prerequisites)
  • GCP 설정 (GCP Setup)
  • 빌드된 바이너리를 사용한 빠른 설정 (Quick setup using prebuilts)
  • arrakis-restserver 실행 (Run the arrakis-restserver)
  • CLI 또는 py-arrakis 사용 (Use the CLI or py-arrakis)
• 퀵스타트 (Quickstart)
  • SDK
  • MCP
  • Computer Use를 위한 GUI (GUI For Computer Use)
  • CLI 사용법 (CLI Usage)
• 아키텍처 및 기능 (Architecture And Features)
• 커스터마이징 (Customization)
• 기여 (Contribution)
  • 법적 정보 (Legal Info)
    • 기여자 라이선스 동의서 (Contributor License Agreement)
    • 라이선스 (License)
• 라이선스 (License)

데모 (Demo)

Claude가 MCP를 통해 Arrakis를 사용하여 실시간 Google Docs 클론을 코딩하는 모습을 시청하세요. 심지어 진행 상황을 체크포인트로 저장하기 위해 샌드박스 (sandbox)를 스냅샷 (snapshot) 찍기도 합니다.

설정 (Setup)

사전 요구 사항 (Prerequisites)

• cloud-hypervisor는 Linux 머신에서 가상화 (virtualization)를 위해 /dev/kvm에서만 작동합니다. 따라서 Linux 머신만 지원합니다.

• 다음 명령어를 실행하여 호스트에서 가상화가 활성화되어 있는지 확인하세요.

  복사

  stat /dev/kvm
  

  1

  2

GCP 설정 (GCP Setup)

• GCE VM에 Arrakis를 설정하려면 GCP 설정의 지침을 따르세요.

빌드된 바이너리를 사용한 빠른 설정 (Quick setup using prebuilts)

• 우리의 setup.sh 스크립트와 빌드된 바이너리 (prebuilt binaries)를 활용하여 Arrakis를 쉽게 설정할 수 있습니다.
  복사

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

  1

  2

  3

arrakis-restserver 실행 (Run the arrakis-restserver)

• 이제 모든 바이너리와 이미지가 다운로드된 폴더가 준비되었습니다. 항상 arrakis-restserver를 먼저 실행해야 합니다.
  복사

  cd arrakis-prebuilt
  sudo ./arrakis-restserver
  

  1

  2

  3

CLI 또는 py-arrakis 사용 (Use the CLI or py-arrakis)

• CLI 또는 py-arrakis를 사용하여 VM을 생성하고 관리할 수 있습니다.
  복사

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

  1

  2

  3

Quickstart

SDK

Arrakis는 VM (가상 머신)을 원활하게 생성, 관리 및 상호작용할 수 있는 Python SDK py-arrakis를 제공합니다.

• SDK 설치

  복사

  pip install py-arrakis
  

  1

  2

• Linux 머신에서 arrakis-restserver를 실행하려면 Usage의 지침을 따르거나, 공식 릴리스 페이지에서 빌드된 바이너리를 다운로드하세요.

• py-arrakis를 사용하여 arrakis-restserver와 상호작용하세요.

• 신뢰할 수 없는 코드 실행

  복사

  # `arrakis-restserver`가 실행 중인 ip:port로 교체하세요.
  sandbox_manager = SandboxManager('http://127.0.0.1:7000')
  

  1

  2

  3

...

- 샌드박스 (Sandbox) 스냅샷 및 복구
  ```python
  # 샌드박스를 시작하고 파일에 데이터를 작성합니다.
  sandbox_name = 'agent-sandbox'
  sandbox = sandbox_manager.start_sandbox(sandbox_name)
...

MCP

• Arrakis는 또한 Claude Desktop App, Windsurf, Cursor 등이 샌드박스를 생성하고 관리할 수 있게 해주는 MCP 서버를 제공합니다.

• 다음은 claude_desktop_config.json 샘플입니다.

  복사

  {
      "mcpServers": {
        "arrakis": {
  

  1

  2

  3

  4

...

___

### GUI For Computer Use

- 모든 샌드박스에는 부팅 시 실행되는 VNC 서버가 포함되어 있습니다. 또한 Chrome이 사전 설치되어 있습니다.

- Arrakis는 또한 `arrakis-restserver`가 실행 중인 개발 서버의 포트를 통해 VNC 서버를 노출할 수 있도록 포트 포워딩 (Port Forwarding)을 처리합니다.

- 샌드박스를 시작하고 VNC 연결 세부 정보를 포함한 샌드박스 메타데이터를 가져오세요.

  ```python
  # `arrakis-restserver`가 실행 중인 ip:port로 교체하세요.
  sandbox_manager = SandboxManager('http://127.0.0.1:7000')
  sb = sandbox_manager.start_sandbox('agent-sandbox')
...

• 응답의 port_forwards 필드에서 VNC 연결 세부 정보를 가져올 수 있습니다. VNC 서버는 포트 포워딩 (port forward) 항목의 설명(description) gui로 표시됩니다. VNC 서버에 연결하기 위해 host_port 필드를 사용합니다.
  복사

  {
    'name': 'agent-sandbox',
    'status': 'RUNNING',
  

  1

  2

  3

  4

...

- [VNC 클라이언트](https://github.com/novnc/noVNC)를 사용하여 VNC 서버에 연결하고 GUI에 접속하세요.
```bash
# 포트 3000이 샌드박스 내부에서 실행 중인 VNC 서버로 포워딩된 호스트 포트임을 확인할 수 있습니다.
./utils/novnc_proxy --vnc <dev-server-ip>:3000

CLI 사용법

• Arrakis는 VM을 생성하고 관리할 수 있는 즉시 사용 가능한 CLI 클라이언트를 제공합니다.

• Setup 섹션에 자세히 설명된 대로 arrakis-restserver를 시작하세요.

• 별도의 셸 (shell)에서 CLI 클라이언트를 사용하여 VM을 생성하고 관리합니다.

• foo라는 이름의 VM을 시작합니다. 이는 VM과 상호작용하는 데 사용할 수 있는 VM에 대한 메타데이터 (metadata)를 반환합니다.

  복사

  ./out/arrakis-client start -n foo
  

  1

  2
  복사

  started VM: {"codeServerPort":"","ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
  

  1

  2

• VM에 SSH로 접속합니다.

  • SSH 자격 증명 (credentials)은 여기에 구성되어 있습니다.
  복사

  # 반환된 IP를 사용하세요. 비밀번호는 "elara0000"입니다.
  ssh elara@10.20.1.2
  

  1

  2

  3

• foo라는 이름의 VM을 조사합니다.

  복사

  ./out/arrakis-client list -n foo
  

  1

  2
  복사

  VM: {"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
  

  1

  2

• 모든 VM을 나열합니다.

  복사

  ./out/arrakis-client list-all
  

  1

  2
  복사

  VMs: {"vms":[{"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}]}
  

  1

  2

• VM을 중지합니다.

  복사

  ./out/arrakis-client stop -n foo
  

  1

  2

• VM을 삭제합니다.

  복사

  ./out/arrakis-client destroy -n foo
  

  1

  2

• VM 스냅샷 생성 및 복구 (Snapshotting and Restoring the VM).

  • VM 스냅샷 생성(snapshotting) 및 해당 스냅샷을 사용하여 VM을 복구(restore)하는 기능을 지원합니다. 현재는 원본 VM과 동일한 IP를 사용하도록 VM을 복구합니다. 동일한 호스트에서 VM을 복구할 계획이라면, 복구하기 전에 원본 VM을 중지(stop)하거나 삭제(destroy)해야 합니다. 향후에는 이것이 제약 사항이 되지 않을 것입니다.
  복사

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

  1

  2
  복사

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

  1

  2
  복사

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

  1

  2

아키텍처 및 기능 (Architecture And Features)

arrakis는 다음과 같은 서비스와 기능을 포함합니다.

• REST API

  • arrakis-restserver
    • VM을 시작(start), 중지(stop), 삭제(destroy), 전체 목록 조회(list-all) 할 수 있도록 REST API를 노출하는 데몬(daemon)입니다. 시작된 모든 VM은 이 서버에 의해 관리됩니다. 즉, 각 VM의 수명은 이 데몬의 수명과 연결됩니다.
    • API는 api/server-api.yaml에서 확인할 수 있습니다.
    • 코드
  • arrakis-client
    • arrakis-restserver와 상호작용하여 VM을 생성(spawn)하고 관리하는 데 사용할 수 있는 Golang CLI입니다.
    • 코드

• Python SDK

  • 공식 Python SDK를 확인해 보세요 - py-arrakis

• 보안 (Security)

  • 각 샌드박스(sandbox)는 MicroVM에서 실행됩니다.
    • MicroVM은 firecracker 및 cloud-hypervisor와 같은 Rust 기반 가상 머신 관리자(Virtual Machine Managers, VMM)를 사용하는 경량 가상 머신(Virtual Machines, 전통적인 VM과 비교 시)입니다.
    • Arrakis는 VMM으로 cloud-hypervisor를 사용합니다.
  • 샌드박스 내에서 실행되는 신뢰할 수 없는 모든 코드는 호스트 머신뿐만 아니라 다른 에이전트(agents)로부터 격리됩니다.
  • 각 샌드박스의 루트 파일 시스템(root filesystem)을 보호하기 위해 overlayfs를 사용합니다.

• Customization (커스터마이징)

  • Dockerfile 기반의 rootfs 커스터마이징.
    • Dockerfile을 조작하여 VM의 rootfs에 패키지와 바이너리를 쉽게 추가할 수 있습니다.
  • 게스트(guest)를 위한 즉각적인 네트워크 설정.
    • 각 샌드박스는 호스트의 Linux bridge에 추가되는 tap 디바이스를 할당받습니다.
    • 샌드박스에 대한 SSH 접속을 지원합니다.
  • 샌드박스용 사전 빌드된 Linux 커널
    • 또는 VM을 시작할 때 arrakis-client에 사용자 정의 커널을 전달할 수 있습니다.

Customization (커스터마이징)

• 상세 README에서 샌드박스에서 실행되는 기본 패키지 및 바이너리를 커스터마이징하는 방법을 다룹니다.

Contribution (기여)

arrakis에 기여를 고려해 주셔서 감사합니다! 🎉

자유롭게 PR(Pull Request)을 올려주세요. 상세한 기여 가이드(contribution guide)가 곧 제공될 예정입니다.

Legal Info (법적 정보)

Contributor License Agreement (기여자 라이선스 동의서)

패치 및 기타 기여를 수락하기 위해서는 Arrakis 기여자 라이선스 동의서("CLA")를 채택해야 합니다. 이 프로세스를 시작하려면 abshkbh@gmail.com으로 메시지를 보내주세요.

Arrakis는 기여자의 CLA 상태를 추적하기 위해 CLA Assistant라는 도구를 사용합니다. CLA Assistant는 귀하의 pull request에 CLA 서명 여부를 나타내는 댓글을 게시합니다. CLA에 서명하지 않은 경우, 기여를 수락하기 전에 서명이 필요합니다. CLA 서명은 일회성 프로세스이며, 향후 Arrakis에 대한 모든 기여에 유효하며, GitHub 계정으로 로그인하여 1분 이내에 완료할 수 있습니다.

License (라이선스)

Arrakis에 기여함으로써, 귀하는 귀하의 기여가 GNU Affero General Public License v3.0에 따라 라이선스가 부여되며 상용 소프트웨어로 취급됨에 동의합니다.

License (라이선스)

이 프로젝트는 GNU Affero General Public License v3.0에 따라 라이선스가 부여됩니다. 상용 라이선스의 경우, abshkbh@gmail.com으로 문의해 주세요.