Remote Coding Runtime

一个与模型无关、与客户端无关的远程编码运行时，拥有一个稳定的 Cloudflare 控制平面和仅出站连接的本地 Runner。

ChatGPT / Claude / Cursor / any MCP client
          │ HTTPS stateless MCP
          ▼
Cloudflare Worker
  Admin UI · RegistryDO · RunnerDO
          │ authenticated outbound WebSocket RPC
          ▼
Local Runner
  filesystem · transactional patch · Git · process · persistent jobs

Cloudflare 不执行代码，也不调用 AI 模型。MCP 客户端负责推理；Runner 负责文件系统、Git 和进程工作。关闭浏览器、聊天、MCP 请求或 Runner WebSocket 不会停止已经启动的作业。

Architecture

• Worker： 唯一的公共 MCP/控制平面端点。它对 MCP 客户端 URL 进行身份验证，提供小型管理 UI，并路由有界 RPC 消息。

• RegistryDO： 用于 Runner、工作区、历史作业、管理员密码/会话状态和 MCP 客户端凭据的 SQLite 元数据。

• RunnerDO： 每个 Runner 一个可休眠的 Durable Object。它拥有当前出站的 Runner WebSocket 和关联的 RPC 桥接；它从不执行编码工作。

• Runner： 一个仅出站连接的 Node 进程，带有受信任的工作区映射、路径限制、补丁/Git 服务、本地子进程以及持久化日志/作业元数据。

• Protocol： packages/protocol 提供严格的 TypeScript 模式和生成的、与语言无关的 JSON Schema，供未来的 Go/Rust Runner 使用。

Cloudflare 核心仅使用 Workers 和由 SQLite 支持的 Durable Objects。它不使用 OAuth、KV、D1、Queues、R2、Sandbox、Containers、Dynamic Workers、隧道、入站 SSH、GitHub Actions 运行时或 AI 模型 API。

Related MCP server: cloud-to-local

Deploy

要求：Node.js 20+、npm、Git、Wrangler，以及一个启用了 SQLite 支持的 Durable Objects 的 Cloudflare 账户。

git clone https://github.com/aloneio/remote-coding-runtime.git
cd remote-coding-runtime
npm install
npm test
npm run typecheck
npm run build
npm run validate:worker

配置 Runner 管理和内部控制通道所使用的三个生产环境密钥：

cd apps/worker
npx wrangler secret put ADMIN_TOKEN
npx wrangler secret put RUNNER_TOKEN_PEPPER
npx wrangler secret put INTERNAL_CONTROL_SECRET

然后仅在准备就绪时部署：

npx wrangler deploy --config wrangler.jsonc

npm run validate:worker 使用 --dry-run 运行 Wrangler。请验证其输出中包含 --dry-run: exiting now；它并不证明已部署账户的配额或生产网络行为。

First setup

打开已部署的根 URL，例如：

https://mcp.aloneio.com/

全新的 RegistryDO 会显示：

Welcome to Remote Coding Runtime
Create administrator password

第一个有效的设置请求以原子方式获胜。不需要引导密码。部署后立即设置密码。如果未初始化的公共实例被其他人认领，请删除/重置其 Cloudflare 状态并重新部署。

密码不以明文存储。Registry 存储带随机盐的、带版本号的 PBKDF2-HMAC-SHA-256 验证器。登录会创建一个随机的七天不透明会话；浏览器收到 Secure、HttpOnly、SameSite=Strict、Path=/ Cookie，而 RegistryDO 只存储其 SHA-256 哈希。更改密码会使所有现有会话失效。

管理状态更改请求使用绑定会话的 CSRF 令牌和同源检查。设置和登录也使用短期预认证 CSRF Cookie。

Add a Runner

Runner 身份验证与管理员登录和 MCP 客户端凭据保持独立。通过受 ADMIN_TOKEN 保护的 API 注册或轮换 Runner：

curl -sS -X POST https://mcp.aloneio.com/admin/runners \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"runner_id":"home-pc"}'

明文 Runner 令牌仅在成功注册/轮换时返回。请安全存储它，然后启动 Runner：

CODING_RUNNER_TOKEN='returned-runner-token' \
  npx tsx apps/runner/src/cli.ts start \
  --server wss://mcp.aloneio.com \
  --runner-id home-pc \
  --workspace zero=/home/me/code/zero\;writable\;noshell

工作区语法：

--workspace id=path[;readonly|writable][;shell|noshell]

默认值为 readonly;noshell。生产环境要求 wss://；明文 ws:// 仅在与 --insecure-local 一起用于环回时才被接受。

Runner 只需要出站互联网访问。它不暴露 HTTP、MCP、OAuth、SSH 或入站端口。

Create MCP clients

在 / 登录，然后使用 /admin 仪表板：

1. 输入名称，例如 ChatGPT Web、Claude 或 Cursor Desktop。

2. 选择 Read、Write 和/或 Execute 作用域。

3. 按下 Create。

4. 立即复制生成的 URL。它只显示一次。

Example:

https://mcp.aloneio.com/fJ3...43-character-base64url-secret...x92/mcp

只需在 MCP 客户端中配置该 URL。不需要 OAuth 流程、回调或额外的 Bearer 头。每个客户端必须有自己的 URL：

ChatGPT → secret A
Claude  → secret B
Cursor  → secret C

仪表板支持：

• 创建

• 重命名

• 轮换

• 撤销

• 每个客户端的 coding:read、coding:write、coding:exec 作用域

• 创建时间/最后使用时间/状态/密钥前缀显示

轮换会立即使旧 URL 失效，并只显示一次替换 URL。撤销会使该 URL 返回与未知密钥相同的 404 Not Found。

Secret URL security model

/<secret>/mcp 是 API 凭据。请像对待密码一样对待完整 URL：

• 不要发布它；

• 不要将其包含在截图中；

• 不要将其提交到 Git；

• 不要将其粘贴到日志、问题或分析中；

• 为每个 MCP 客户端/设备创建不同的 URL；

• 如果怀疑泄露，请立即轮换。

应用程序从不记录传入的 URL/路径，只存储 SHA-256 验证器和一个简短显示前缀。MCP/管理员响应使用 Cache-Control: no-store；HTML 还使用 Referrer-Policy: no-referrer、限制性 CSP、nosniff 和框架阻止。应用程序之外的基础设施仍可能记录请求路径，因此请配置 Cloudflare 日志脱敏，并依靠轮换/撤销进行恢复。

Tool catalog

Runtime

runner_list
runner_info
workspace_list
env_info

Filesystem

fs_read
fs_list
fs_search
fs_apply_patch

Execution and persistent jobs

exec_start
exec_run
job_list
job_get
job_logs
job_cancel
job_input

Git

git_status
git_diff

coding:read 允许运行时/文件系统读取、job_list/job_get/日志以及 Git 检查。coding:write 允许打补丁。coding:exec 允许进程启动/运行/取消/输入。作业在单管理员实例内共享，而不是由某个 MCP 客户端拥有：只要 Claude 具备所需作用域，它就可以发现并读取之前由 ChatGPT 创建的作业。

Persistent jobs

exec_start 会立即返回 job_id。Runner 在以下位置持久化本地权威状态：

~/.remote-coding-runner/state/
├── runner.json
└── jobs/<job_id>/
    ├── meta.json
    ├── stdout.log
    └── stderr.log

Worker 只存储有界元数据。job_list 读取 RegistryDO 快照，因此即使 Runner 离线也能工作。完整的 stdout/stderr 保留在 Runner 上，一旦 Runner 在线，就可以通过分页的 job_logs 读取。

Runner 同步会更新插入当前/最近的作业，而不会仅仅因为旧的历史记录被从有界快照中省略就将其删除。Registry 会保留活动/非终止作业，以及每个 Runner 最多 1,000 个终止作业。作业可能记录 created_by_client_id 用于审计，但该字段不限制跨客户端访问。

Runner 重启后，仍然匹配其已保存 PID/指纹的进程会变为 unknown。在 job_get、job_list 和同步期间的惰性对账会使其在存活时保持 unknown，并在消失后将其改为 interrupted，因为无法获得真实的退出结果。只有当持久证据证明该 Runner 确实送达了终止请求时，恢复的取消才会变为 cancelled；不会凭空发明退出码。

默认情况下，磁盘上的日志文件保持完整且无界。请监控 Runner 的磁盘使用情况。

Filesystem and patch safety

MCP 请求只提供 runner_id、workspace_id 和工作区相对路径。Runner 拒绝：

• POSIX 绝对路径；

• Windows 驱动器、UNC 和设备路径；

• NUL 字节和 .. 遍历；

• 未知的工作区 ID；

• 符号链接/联接的祖先和逃逸；

• 直写符号链接；

• 对只读工作区的写入。

fs_read 和 job_logs 使用 UTF-8 安全的字节游标。包含中文、表情符号和带重音字符的小页面可以被精确拼接，不会出现替换字符。

fs_apply_patch 支持 Add/Update/Delete/Move 操作、预期的 SHA-256 基线、精确的 hunk 匹配、同目录暂存/备份、回滚、BOM/换行/模式保留，以及有界结构化结果。诸如 invalid_patch、missing_file、target_exists、baseline_changed、hunk 错误、patch_install_failed 和 patch_rollback_failed 等稳定的安全错误会到达 MCP，而不会暴露主机绝对路径。

这是一个工作区/路径授权边界，不是对抗性操作系统沙箱。请在具有受限挂载、密钥和网络访问权限的外部 VM/容器中运行不受信任的仓库或命令。

Timeouts and environment discovery

共享协议常量使截止时间保持一致：

normal Runner operation maximum: 8,000 ms
Worker → Runner bridge timeout: 12,000 ms

这留出四秒的传输/回复余量。exec_run 和 Git 使用共享的本地限制；更长时间的工作必须使用 exec_start。

env_info 缓存有界并行探测，涵盖平台、架构、主机名、shell、Node、npm、pnpm、Python、Git、Go、rustc、Cargo 和 Docker。缺失或超时的工具返回 { "available": false }，而不是使请求失败。

Tests

npm test
npm run typecheck
npm run build
npm run validate:worker

该套件包括协议测试、Runner 文件系统/进程/补丁/Git/恢复测试、Worker Durable Object 和管理员/客户端认证测试，以及真实的本地 Wrangler + 真实 Runner E2E 测试。覆盖范围包括：

• 原子一次性设置；

• PBKDF2 密码/会话行为、过期、登出、密码失效和 CSRF；

• 每个客户端密钥 URL 的创建/轮换/撤销/404/作用域强制；

• 真实的 MCP → Worker → Runner fs_read；

• UTF-8 文件/日志分页；

• MCP 请求关闭后的持久执行；

• Runner 传输断开、本地继续、重连和同步；

• 客户端 A 启动一个作业，客户端 B 在离线时通过 job_list 发现它；

• 遍历、符号链接、只读、补丁、Git、超时、输出和并发边界。

本地测试不能证明特定 Cloudflare 账户的配额、生产环境边缘日志脱敏、互联网客户端兼容性或已部署的重启/休眠事件。部署仍然是操作者负责的验收步骤。

Scope deliberately excluded

该 MVP 不包含 MCP Tasks、PTY/Web 终端、多用户账户、组织、团队、计费、AI 代理、RAG、浏览器自动化、GitHub Actions 运行时、Cloudflare Sandbox 或 Cloudflare Containers。

Acknowledgements and license

这是一个独立的 Apache-2.0 实现。设计研究参考了：

• xyTom/coding-tools-mcp，Apache-2.0 + NOTICE；

• volter-ai/volter-tunnel，Apache-2.0 + NOTICE；

• Hiroshimeow/agent-mcp-gateway，MIT；

• Cloudflare Workers、Durable Objects、WebSocket Hibernation、Agents MCP handler 和 MCP TypeScript SDK 文档。

研究期间，所请求的 davidlosasgonzalez/codeagent-mcp 仓库在公共 URL 上不可用，因此没有使用其中的任何代码或许可证。