Code Remote

🚀 Code Remote

Code Remote 允許你通過任何支持 MCP 的 AI 客戶端，在你的設備上執行命令。它將 MCP（模型上下文協議）與你的本地設備相連接，使 AI 助手能夠運行 shell 命令、讀寫文件以及瀏覽你的文件系統，你可以通過手機或任何網頁瀏覽器來完成這些操作。

🚀 快速開始

你可以選擇以下部署方式：

選項 A：使用 ngrok 進行本地部署（最簡單）

使用 ngrok 進行 HTTPS 隧道，在本地運行所有服務，無需進行雲端部署。

# 終端 1：啟動服務器
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env
docker-compose up -d

# 終端 2：啟動 ngrok 隧道
ngrok http 8080
# 記錄 https://xxx.ngrok-free.app 這個 URL

# 終端 3：啟動代理（本地連接）
cd agent
uv venv && uv pip install -r requirements.txt
source .venv/bin/activate
export AUTH_TOKEN=$(cat ../.env | cut -d= -f2)
export RELAY_URL=ws://localhost:8080/ws/agent
python agent.py

添加到你的 MCP 客戶端：

• URL：https://xxx.ngrok-free.app/sse（你的 ngrok URL）

注意：免費的 ngrok 層級會提供一個隨機的 URL，重啟後會改變。付費計劃提供穩定的子域名。

選項 B：Docker + 反向代理（自託管）

在你自己的基礎設施上，使用合適的域名運行服務器。

# 1. 生成認證令牌
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env

# 2. 啟動服務器
docker-compose up -d

# 3. 設置 HTTPS（見下面的 HTTPS 設置部分）

選項 C：Fly.io（託管）

部署到 Fly.io 以實現自動 HTTPS 和全球可用性。

cd server

# 編輯 fly.toml 並設置你的應用名稱
# 更改：app = "YOUR-APP-NAME"
# 為：app = "yourname-code-remote"

fly launch --name YOUR-APP-NAME --region dfw --no-deploy
fly volumes create code_remote_data --size 1 --region dfw
fly secrets set AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy

你的 URL 將會是：

• MCP 端點：https://YOUR-APP-NAME.fly.dev/sse
• WebSocket：wss://YOUR-APP-NAME.fly.dev/ws/agent

安裝代理（選項 B 和 C）

原生代理（直接在你的設備上運行）：

cd agent
./setup.sh
# 輸入你的中繼 URL（例如，wss://your-server.example.com/ws/agent）
# 輸入你的認證令牌
./run.sh

沙盒代理（在 Docker 容器中運行）：

# 使用容器化代理運行完整堆棧
docker-compose --profile full up -d

沙盒代理以非 root 用戶身份在隔離的 Linux 環境中運行，包含常見的開發工具（git、curl、vim、ripgrep 等）。文件訪問限制在容器內的 /home/agent/workspace。

連接你的 AI 客戶端

添加到你的 MCP 客戶端設置：

• URL：https://your-server.example.com/sse

對於 Claude.ai：設置 > 連接器 > MCP

✨ 主要特性

• 可通過任何 MCP 兼容的 AI 客戶端，在本地設備上執行命令。
• 支持多種部署方式，包括本地部署、自託管部署和託管部署。
• 提供沙盒代理模式，增強安全性。
• 支持 Tailscale 集成，進一步提高安全性。

📦 安裝指南

前提條件

• uv - 快速 Python 包管理器（代理所需）

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Python 3.10+ - 用於運行代理
• Docker - 用於自託管服務器部署（選項 A 和 B）
• Fly.io CLI - 用於託管部署（僅選項 C）

💻 使用示例

基礎用法

你可以在 MCP 客戶端中調用以下工具：

📚 詳細文檔

• 設置指南 - 完整的安裝說明
• 部署 - Fly.io 部署和管理
• 架構 - 系統設計和安全性

🔧 技術細節

架構

雲/自託管設置

+----------------+          +-------------------+          +----------------+
|                |   SSE    |                   |    WS    |                |
|   AI Client    |<-------->|  Server (Cloud)   |<-------->|     Agent      |
|   (MCP)        |   MCP    |                   |  Relay   |   (Daemon)     |
+----------------+          +-------------------+          +----------------+

使用 ngrok 的本地設置（所有服務在一臺設備上）

+----------------+          +-------------------+          +---------------------------+
|                |  HTTPS   |                   |          |      Your Machine         |
|   AI Client    |--------->|   ngrok tunnel    |--------->| +-------+     +-------+   |
|   (MCP)        |          |                   |          | |Server |<--->| Agent |   |
+----------------+          +-------------------+          | +-------+     +-------+   |
                                                           +---------------------------+

數據流

1. 你與 AI 助手（Claude.ai 等）進行聊天。
2. AI 調用 MCP 工具（run_shell_command、read_file 等）。
3. 服務器將命令排隊，並通過 WebSocket 將其發送給連接的代理。
4. 代理在你的設備上執行命令並返回結果。
5. 結果通過 SSE 流回 AI。

HTTPS 設置

MCP 客戶端通常需要 HTTPS。如果你使用 Docker 進行自託管，你需要一個反向代理。以下是一個使用 Caddy 的簡單示例：

# 安裝 Caddy (https://caddyserver.com/docs/install)
# 創建 Caddyfile:
cat > Caddyfile << 'EOF'
your-domain.com {
    reverse_proxy localhost:8080
}
EOF

# 運行 Caddy（通過 Let's Encrypt 自動配置 TLS）
caddy run

其他選項：

• nginx：使用 certbot 獲取 Let's Encrypt 證書
• Traefik：內置 ACME 支持，用於自動 TLS
• Cloudflare Tunnel：免費選項，為你處理 TLS

安全性

• 所有組件之間採用基於令牌的認證。
• 代理將文件訪問限制在主目錄、/tmp、/var/tmp。
• 所有流量通過 HTTPS/WSS 加密。
• 命令記錄到 SQLite 以進行審計跟蹤。
• 沙盒模式：在 Docker 容器中運行代理以實現完全隔離。
• Tailscale 集成：將代理連接限制在你的私有 Tailscale 網絡。

Tailscale 設置（推薦）

為了增加安全性，你可以配置服務器僅接受來自你的 Tailscale 網絡的代理連接。這確保即使你的 AUTH_TOKEN 被洩露，只有你的 Tailnet 上的設備才能作為代理連接。

1. 生成一個 Tailscale 認證密鑰： 前往 https://login.tailscale.com/admin/settings/keys 並創建一個新的認證密鑰：

• 勾選“可重複使用”（以便服務器在重啟後可以重新連接）
• 可選地勾選“臨時”
• 注意：密鑰最長 90 天后過期

2. 將認證密鑰設置為 Fly.io 機密：

fly secrets set TAILSCALE_AUTHKEY=tskey-auth-xxxxx -a YOUR-APP-NAME

3. 部署服務器：

cd server
fly deploy

4. 配置代理通過 Tailscale 連接： 部署後，在 Fly.io 日誌中找到你的服務器的 Tailscale IP：

fly logs -a YOUR-APP-NAME | grep "peerapi: serving"
# 查找：peerapi: serving on http://100.x.x.x:xxxxx

更新你的代理的 .env：

RELAY_URL=ws://100.x.x.x:8080/ws/agent

禁用 Tailscale 要求

要允許來自任何 IP 的代理連接（安全性較低）：

fly secrets set REQUIRE_PRIVATE_NETWORK=false -a YOUR-APP-NAME

📄 許可證

本項目採用 GNU Affero General Public License v3.0（AGPL - 3.0）許可。請參閱 LICENSE。

作者

Drew Cain (@groksrc)

項目結構

code-remote/
├── docker-compose.yml   # 自託管部署
├── .env.example         # 環境模板
│
├── server/              # 服務器（Docker 或 Fly.io）
│   ├── server.py        # 組合的 MCP + 中繼服務器
│   ├── start.sh         # 啟動腳本（Tailscale + 服務器）
│   ├── Dockerfile
│   ├── fly.toml         # Fly.io 配置（更改應用名稱）
│   └── requirements.txt
│
├── agent/               # 代理（原生或容器化）
│   ├── agent.py         # WebSocket 客戶端守護進程
│   ├── Dockerfile       # 沙盒 Linux 代理
│   ├── requirements.txt
│   ├── setup.sh         # 設置腳本（提示輸入 URL）
│   ├── run.sh           # 運行腳本（帶日誌輪轉）
│   ├── logs/            # 代理日誌（自動輪轉）
│   └── com.code.remote-agent.plist
│
└── docs/                # 文檔
    ├── SETUP.md
    ├── DEPLOYMENT.md
    └── ARCHITECTURE.md