Manus SDK Linux — WSL2 + Docker 設定（integrated vs remote）

Context

在 Windows WSL2 環境使用 Manus SDK（手套 dongle），研究 integrated mode 能否在 Docker 容器內讀到 USB dongle，並整理 docker compose 對應設定。參考文件：Manus SDK Linux 3.1.0。

Key Insights

• 架構選擇先決定一切：SDK 有 integrated（直吃 dongle）和 remote（透過網路連 Core）兩種模式。Manus Core 只跑 Windows，在 Windows+WSL 環境建議先嘗試 remote mode——dongle 插 Windows、Core 跑 Windows、WSL 容器 --net=host 連過去，完全跳過 usbipd/udev/privileged，省一大堆坑。
• Integrated on WSL2 需要兩道 WSL 專屬關卡（文件沒提，原生 Linux 不用管）：
  1. usbipd：WSL2 = Hyper-V VM，預設看不到 Windows USB。要先 usbipd bind/attach --wsl 把 dongle 過繼進來，lsusb 看到（VID 3325 或 1915:83fd）才算過關。
  2. systemd/udevd：WSL2 預設不跑 systemd，udev rule 不會觸發，/run/udev 是空的，HIDAPI（libudev）列舉不到裝置。需在 /etc/wsl.conf 加 [boot] systemd=true，wsl --shutdown 重啟。
• udev rule（99-manus.rules 內容）：

  # HIDAPI/libusb
  SUBSYSTEMS=="usb", ATTRS{idVendor}=="3325", MODE:="0666"
  SUBSYSTEMS=="usb", ATTRS{idVendor}=="1915", ATTRS{idProduct}=="83fd", MODE:="0666"
  # HIDAPI/hidraw
  KERNEL=="hidraw*", ATTRS{idVendor}=="3325", MODE:="0666"
  

• 官方 docker run（integrated）：--privileged -v /dev:/dev -v /run/udev:/run/udev 三個缺一不可：--privileged 開全裝置 cgroup、/dev 帶入 hidraw+usb 節點、/run/udev 讓 libudev 能列舉。
• 啟動順序固定：usbipd attach → 確認 lsusb//dev/hidraw* → 再 docker compose run。

Docker Compose 對應設定

services:
  manus-integrated:
    image: manus-linux-integrated
    privileged: true
    ports:
      - "5000:5000"
    volumes:
      - /dev:/dev
      - /run/udev:/run/udev
    stdin_open: true
    tty: true
    command: /bin/bash

啟動指令（進互動 shell）：

docker compose run --rm --service-ports manus-integrated

用 run 而非 up：up 會讓 /bin/bash 立即結束容器；--service-ports 才會發布 ports:。

Connections

• 2026-06-12-linux-usb-docker-device-mount