Tailscale Compute

Tailscale Compute MCP

通过 MCP 编码 Agent，在自己的远程计算节点上运行构建、测试和基准测试。

编码 Agent 会在本地计算机上编辑文件。此 MCP 服务通过 rsync 复制项目，并且只有在 Agent 调用 compute_run 时才通过 SSH 运行命令。

这是一个独立项目，并非官方 Tailscale 产品，也未获 Tailscale Inc. 背书。Tailscale 是 Tailscale Inc. 的商标。

发布状态

此软件包处于 Beta 阶段。

• 完整流程已在一台 Mac 笔记本电脑和一台 Apple M4 Mac mini 上运行。
• 此服务包含 Linux 探测功能和 NVIDIA 设备清单支持。
• Linux 解析已有自动化测试覆盖。
• 此版本尚未在真正的 NVIDIA DGX Spark 上运行。请勿将 Linux 或 NVIDIA 的结果视为已通过 DGX Spark 验证。

工作原理

MCP coding agent
    |
    | local stdio
    v
Tailscale Compute MCP
    |
    | rsync and SSH through the user's tailnet
    v
Mac or Linux compute node

此软件包在本地计算机上运行。远程节点上不会运行 MCP 服务。项目作者不会收到你的代码、凭据、命令输出或 Tailscale 流量。

安全警告

compute_run 可以使用远程 SSH 用户的权限运行任何非交互式命令。请将其视为远程代码执行。

• 在远程节点上使用专用的非 root 账户。
• compute_status 会报告远程用户 ID，并在 SSH 用户为 root 时发出警告。请使用非 root 用户运行计算任务，以免遭入侵的构建过程控制整个节点。
• 命令启动、工件获取和成功的工作区删除操作都会记录在本地审计日志中。日志不会包含环境变量值、标准输入或凭据。
• 不要自动批准命令、获取、取消或删除工具。
• 不要将密码、SSH 私钥或 Tailscale 身份验证密钥放入 MCP 配置中。
• 使用 SSH 代理或 Tailscale SSH。
• 使用 Tailscale 策略规则限制访问。
• 使用前请阅读 SECURITY.md。

要求

本地计算机

• Node.js 20 或更高版本。
• Tailscale 已连接到与远程节点相同的 tailnet。
• OpenSSH 客户端。
• 支持 --include 和 --exclude 的 rsync。
• 支持本地 stdio 服务的 MCP 宿主。

此 Beta 版本支持 macOS 和 Linux 本地系统。

远程节点

• Darwin 或 Linux。
• 已连接 Tailscale。
• SSH 服务端。
• rsync 可通过 PATH 使用。
• 已知的 SSH 主机密钥。
• 项目所需的工具链。

除非远程工作负载使用 Node.js，否则 MCP 软件包不要求远程节点安装 Node.js。

设置 Mac mini

1. 在两台 Mac 上安装并连接 Tailscale。
2. 在 Mac mini 上打开系统设置，选择通用，再选择共享，然后开启远程登录。
3. 将本地公钥添加到远程账户：

ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]

4. 验证主机密钥和非交互式访问：

ssh [email protected] /usr/bin/true

5. 检查远程工具：

ssh [email protected] '/bin/zsh -lc "rsync --version"'

处于睡眠状态或已关机的 Mac 可能无法接受 Tailscale 连接。必要时，请配置 macOS 网络唤醒。此 MCP 服务不会发送唤醒数据包。

设置 Linux 节点

按照适用于你的 Linux 发行版的 Tailscale 官方说明安装并连接 Tailscale。然后安装 SSH 服务端和 rsync。

对于 Ubuntu 或 Debian：

sudo apt-get update
sudo apt-get install --yes openssh-server rsync
sudo systemctl enable --now ssh

使用标准 SSH 密钥：

ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]
ssh [email protected] /usr/bin/true

在受支持的 Linux 节点上，可以使用 Tailscale SSH 代替分发 SSH 密钥。你的 Tailscale 策略必须允许网络连接和 SSH 连接。

在 MCP 宿主中安装

固定软件包版本。不要使用未固定版本的软件包来执行 Agent 命令。

Oh My Pi（OMP）

运行默认 OMP 配置的安全设置命令：

npx -y @dylantirandaz/[email protected] \
  setup omp \
  --host [email protected]

该命令会输出 MCP 配置路径和集群技能路径。在写入文件前，它会执行真实的 SSH 连接检查。随后，它会将 tailscale-compute 添加到 ~/.omp/agent/mcp.json，并在 ~/.omp/agent/skills/ 中安装受管理的 tailscale-compute-fleet 技能。它会保留其他服务，固定此软件包版本，并以原子方式替换文件。

如果连接检查失败，该命令不会写入文件。对于格式错误的 JSON、符号链接、设置不同的同名服务，以及同名的非受管理技能，该命令会拒绝执行。

对于命名配置，请手动将服务条目合并到 ~/.omp/profiles/<name>/agent/mcp.json，并将技能安装到该配置的 skills/tailscale-compute-fleet/ 目录中。保留所有现有服务条目：

{
  "mcpServers": {
    "tailscale-compute": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dylantirandaz/[email protected]"
      ],
      "env": {
        "TAILSCALE_COMPUTE_HOST": "[email protected]"
      }
    }
  }
}

将示例主机替换为 SSH 用户和计算节点的 Tailscale IP 地址或完整 MagicDNS 名称。

设置完成后，启动新的 OMP 会话。随后，OMP 会加载该服务，并自动向 Agent 提供集群技能。在现有会话中，/mcp reload 会加载该服务，但新技能要到下一次会话才可用。重新加载或重启后测试服务：

/mcp test tailscale-compute

打印适用于 Claude Code、Cursor、Codex 或 OpenCode 的固定版本配置：

npx -y @dylantirandaz/[email protected] \
  setup print --client <claude|cursor|codex|opencode> \
  --host [email protected]

Claude 输出是用户级命令。Cursor 和 OpenCode 输出为 JSON。Codex 输出是适用于 ~/.codex/config.toml 的 TOML。请将 JSON 或 TOML 输出合并到现有客户端配置中，而不要替换无关条目。

VS Code

创建 .vscode/mcp.json：

{
  "servers": {
    "tailscale-compute": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dylantirandaz/[email protected]"
      ],
      "env": {
        "TAILSCALE_COMPUTE_HOST": "[email protected]"
      }
    }
  }
}

Cursor

创建 .cursor/mcp.json：

{
  "mcpServers": {
    "tailscale-compute": {
      "command": "npx",
      "args": [
        "-y",
        "@dylantirandaz/[email protected]"
      ],
      "env": {
        "TAILSCALE_COMPUTE_HOST": "[email protected]"
      }
    }
  }
}

Claude Code

claude mcp add --scope user \
  --env [email protected] \
  --transport stdio tailscale-compute \
  -- npx -y @dylantirandaz/[email protected]

检查连接

先在 MCP 宿主之外运行该软件包：

[email protected] \
npx -y @dylantirandaz/[email protected] --check

检查成功时会返回 kind: "ready"。此外还会报告：

• 操作系统。
• CPU 架构和型号。
• 逻辑处理器数量。
• 内存。
• 选定的远程 Shell。
• rsync 版本。
• 如果 nvidia-smi 可用，则报告 NVIDIA GPU 清单。
• 实时运行时间、负载平均值、可用内存、存储容量、活动的持久化作业数量，以及 NVIDIA 显存和利用率。

MCP 工具

compute_status

检查 SSH 访问，并报告远程平台、硬件和实时运行状况。

已安装的 GPU 显存信息保留在 hardware.acceleratorInventory 中。当前 GPU 显存使用量、可用显存和利用率保留在 health.acceleratorUsage 中。

compute_doctor

使用选定的 Python 程序，在一个必需的逻辑 CUDA 设备上运行明确的 pytorch 配置：

{
  "profile": "pytorch",
  "pythonProgram": "/opt/project/.venv/bin/python",
  "requiredDevice": "cuda:0",
  "minimumAvailableMemoryBytes": 24000000000
}

选定的 Python 程序必须包含支持 CUDA 的 PyTorch。远程节点还必须提供 nvidia-smi。该配置会报告 NVIDIA 驱动程序、PyTorch CUDA 运行时、可选的 nvcc 编译器、cuDNN、计算能力、可用显存、数据类型和相关后端标志。它会运行已知的 torch.float32 线性运算并验证其结果。此外，它还会验证模型、输入、中间值和输出是否均保留在必需的设备上。缺少必需项时会返回 check_failed；该配置绝不会选择其他 GPU 或回退到 CPU。

该诊断仅验证其小规模运算。请运行实际工作负载并检查其输出，然后再声明应用支持情况。

compute_workspace_status

报告某个本地工作区对应的受管理远程路径、磁盘使用情况、上次成功同步时间、上次运行请求，以及活动的持久化作业 ID。

compute_workspace_delete

仅删除与某个本地工作区对应的受管理远程目录。如果有持久化作业正在运行，则会拒绝删除。重复删除会成功，并报告 existed: false。

compute_run

复制本地工作区，并运行一条非交互式远程命令。

示例：

{
  "program": "npm",
  "arguments": ["test"],
  "syncMode": "incremental",
  "timeoutSeconds": 900
}

对于 Shell 语法，请显式调用受支持的远程 Shell：

{
  "program": "/bin/bash",
  "arguments": ["-lc", "npm ci && npm test"],
  "syncMode": "clean",
  "timeoutSeconds": 1800
}

compute_run 会返回远程退出代码、标准输出、标准错误、同步时间和命令运行时间。为保护 MCP 连接，输出长度受到限制。输出过大时，结果会保留开头和结尾，并报告省略的字节数。

硬件要求

compute_run 和 compute_job_start 接受可选的 requirements 对象。服务器会在启动工作负载前，根据远程硬件检查这些要求。如果某项要求未满足，服务器会返回 kind: "requirements_not_met"，并且不会同步或启动命令。

{
  "program": "python",
  "arguments": ["train.py"],
  "requirements": {
    "platform": "linux",
    "architecture": "x86_64",
    "minimumMemoryBytes": 34359738368,
    "nvidia": {
      "minimumDeviceCount": 1,
      "minimumMemoryBytesPerDevice": 24000000000
    }
  }
}

服务器不会选择设备，也不会回退到 CPU。工作负载必须自行选择并验证所需的加速器。

持久作业

compute_job_start 会同步工作区并启动一个分离运行的命令。远程启动器启动后，它会返回作业 ID。即使 MCP 客户端断开连接，命令仍会继续运行。

{
  "program": "python",
  "arguments": ["train.py"],
  "syncMode": "incremental",
  "timeoutSeconds": 43200,
  "idempotencyKey": "training-run-2026-08-14",
  "label": "baseline",
  "artifactPaths": ["checkpoints/final.pt", "metrics/results.json"]
}

• compute_job_status 会返回 starting、running、completed、failed、 cancelled 或 lost。
• compute_job_logs 会从精确的字节偏移量读取 stdout 或 stderr。在下一次调用中使用 nextOffsetBytes。作业进入终止状态且返回的偏移量达到文件大小后，endOfStream 会变为 true。
• compute_job_cancel 会停止远程进程组。对于已处于终止状态的作业，会返回其现有终止状态。
• compute_job_list 会返回经过筛选和分页的列表，其中包含作业 ID、状态、标签、程序、工作区路径、时间和终止结果。
• compute_job_delete 只会删除处于终止状态的作业。对于活动作业和不安全的远程作业目录，该工具会拒绝删除。

每个终止作业状态都包含输出字节数和 SHA-256 摘要。

幂等键的作用范围为目标和工作区。使用相同请求重试时，会返回现有作业。使用不同请求重复使用该键时，会返回 idempotency_conflict。

命令结束后，声明的制品路径会复制到不可变的作业快照中。终止状态包含更新后的回执，其中记录每个常规文件的路径、大小和 SHA-256 摘要。工作区同步不会删除这些快照。

终止结果会将退出情况归类为正常退出、信号终止、超时、取消、作业丢失或内存耗尽终止。只有进程退出信息与 Linux cgroup 内存事件证据一致时，服务器才会报告内存耗尽。

设置 TAILSCALE_COMPUTE_MAX_ACTIVE_JOBS，可对所有工作区以及使用相同远程根目录的 MCP 服务进程施加统一的节点级限制。作业准入使用原子远程预留。节点已满时，会返回 node_busy，并提供已配置的限制、活动作业 ID，以及仍在准入中的启动数量。它不会排队或启动被拒绝的作业。

compute_fetch

将选定的文件或目录从受管理的远程工作区下载到本地工作区下的本地目标位置。

{
  "paths": ["benchmark/results.json"],
  "localDestination": ".tailscale-compute-results/latest",
  "overwrite": false
}

若要从不可变的终止作业快照中获取所有已声明的制品，请提供作业 ID，并省略 paths：

{
  "jobId": "12345678-1234-4234-8234-123456789abc",
  "localDestination": ".tailscale-compute-results/baseline",
  "overwrite": false
}

提供作业 ID 时，设置 paths 可仅获取选定的已声明制品。若遇到远程符号链接、目标路径越界、未声明的作业制品，或已存在的目标（除非 overwrite 为 true），该工具会拒绝操作。它会报告每个下载的常规文件的大小和 SHA-256 摘要。对于作业文件获取，该工具还会根据不可变的作业回执检查每个下载文件。

运行回执

每次运行和持久化作业都有一份结构化回执。回执记录运行 ID、 服务版本、本地 Git 修订版本、命令参数、环境变量名称、 同步模式、报告的硬件信息、耗时、结果、输出摘要和 获取的制品。持久化回执还可以包含其标签、完整的终止结果和不可变的制品清单。它不会记录 环境变量值、标准输入或幂等键。持久化作业会将 回执存储在远程作业目录中，并在作业进入终态时更新回执。

同步模式

• incremental：更新受管理的远程工作区，并删除本地已不存在的远程文件。
• clean：仅删除经过哈希处理的受管理工作区，重新创建该工作区，然后复制项目。
• none：复用上次的远程快照，不复制本地文件。

每个本地工作区都会映射到以下路径下的稳定远程目录：

.cache/tailscale-compute-mcp

服务器会依次为同一个工作区运行命令。不同工作区可以同时运行。

在相关事件发生之前，compute_workspace_status 会报告 lastSyncAt: { "kind": "never" } 或 lastRunAt: { "kind": "never" }。

排除文件

同步会读取工作区根目录中的 .gitignore 和 .tailscale-compute-ignore。它支持空行、以 # 开头的注释、以 ! 开头的否定规则，以及标准 rsync 模式。它不会读取嵌套的忽略文件。每个忽略文件最多可为 64 KiB，服务器会读取两个文件中总计最多 5,000 条规则。超过这些限制的文件或后续规则会被忽略。

.git/
.env
.env.*
.npmrc
.pypirc
.ssh/
.aws/
.gnupg/
.git-credentials
.netrc
*_history
.curlrc
.wgetrc
*.pem
*.key
*.p12
*.pfx
*.secret
secrets/
node_modules/
.venv/
venv/
target/
__pycache__/
.next/cache/

上述固定排除项具有最高优先级。忽略文件中的否定规则无法将这些文件纳入同步。

将项目专属机密和大型输出文件添加到 .tailscale-compute-ignore。

忽略的文件不会被复制。如果需要的文件被忽略，请在远程节点上创建该文件，或通过显式的 compute_run.environment 条目提供其值。请记住，工具参数对 MCP 主机和模型可见。

配置

变量	必需	默认值	用途
TAILSCALE_COMPUTE_HOST	是	无	SSH 用户名和直连 Tailscale IP 地址或完整 MagicDNS 名称。
TAILSCALE_COMPUTE_LOCAL_ROOT	否	MCP 进程目录	本地项目绝对路径。
TAILSCALE_COMPUTE_REMOTE_ROOT	否	.cache/tailscale-compute-mcp	受管理的远程工作区根目录。
TAILSCALE_COMPUTE_REMOTE_SHELL	否	auto	auto、/bin/sh、/bin/bash 或 /bin/zsh。
TAILSCALE_COMPUTE_CONNECT_TIMEOUT_SECONDS	否	10	SSH 连接超时时间，范围为 1 至 60 秒。
TAILSCALE_COMPUTE_MAX_ACTIVE_JOBS	否	无限制	节点范围内的持久化作业数量上限，范围为 1 至 1024。
TAILSCALE_COMPUTE_AUDIT_LOG	否	~/.config/tailscale-compute-mcp/compute-audit.log	compute_run 记录的本地审计日志路径。

自动选择 shell 时，Darwin 上使用 /bin/zsh。Linux 上如果有 /bin/bash，则使用它；否则使用 /bin/sh。

多个计算节点

对于 OMP，请为每个节点运行一次设置，并为每个服务指定唯一名称：

npx -y @dylantirandaz/[email protected] \
  setup omp \
  --host [email protected] \
  --name compute-mac-mini-1

npx -y @dylantirandaz/[email protected] \
  setup omp \
  --host [email protected] \
  --name compute-mac-mini-2

每条命令都会检查对应节点，并保留其他已命名服务。第一条 命令会安装 fleet skill。后续命令会复用或更新该受管理的 skill。最后一条命令运行完成后，启动新的 OMP 会话。

对于其他 MCP 客户端，请使用不同的名称和主机重复注册该软件包。每个 MCP 服务实例只保留一个目标。

{
  "mcpServers": {
    "compute-mac-mini": {
      "command": "npx",
      "args": ["-y", "@dylantirandaz/[email protected]"],
      "env": {
        "TAILSCALE_COMPUTE_HOST": "[email protected]"
      }
    },
    "compute-linux": {
      "command": "npx",
      "args": ["-y", "@dylantirandaz/[email protected]"],
      "env": {
        "TAILSCALE_COMPUTE_HOST": "[email protected]",
        "TAILSCALE_COMPUTE_REMOTE_SHELL": "/bin/bash"
      }
    }
  }
}

由 Agent 控制的工作流

对于独立任务，让 Agent 查询每个指定 MCP 服务上的 compute_status 和 compute_job_list。Agent 可以根据平台、架构、硬件要求、活动任务数和 负载选择符合条件的节点。重试必须使用相同的服务、幂等键和请求数据。 制品仍由所选节点持有，必须通过 compute_fetch 获取，并验证回执哈希。

此软件包不包含集群调度器或隐藏队列，也不会将普通命令变成分布式程序。只有当项目声明了分布式运行时和启动命令（例如 MLX distributed、Ray 或 MPI）时，程序才能使用多个节点。启动前，将相同的工作区修订版本和运行时版本同步到每个节点。记录每个节点角色和任务 ID，并在取消或清理时验证每个工作进程的状态。

Thunderbolt 线缆可在 Mac 之间提供一种可能的数据平面网络，但不会合并它们的 CPU、GPU 或统一内存。MCP 控制连接应保持在 Tailscale 上，并且仅通过声明的运行时配置使用 Thunderbolt 地址。

MLX 为通过 SSH 连接的主机提供 mlx.launch、TCP 或 Thunderbolt 环形后端，以及适用于受支持 Thunderbolt RDMA 系统的 JACCL。有关主机文件、拓扑、操作系统和 RDMA 要求，请参阅官方 MLX 分布式指南。分布式验证必须检查全局进程数、rank 分配、后端、设备分配，以及依赖每个 rank 的结果。

NVIDIA 工作负载

compute_status 通过 nvidia-smi 报告 NVIDIA 设备。此清单并不能证明工作负载使用了 GPU。compute_doctor 会验证所选设备上的一项小型 PyTorch 操作及其精确 CUDA 设备分配，但不能证明应用程序工作负载使用了 GPU。

GPU 工作负载必须选择预期设备，验证模型、输入、计算和输出的设备分配，并检查有意义的结果。服务不会代表远程命令回退到 CPU。

开发

npm ci
npm run check

针对真实远程节点运行连接检查：

[email protected] node dist/main.js --check

发布前测试软件包内容：

npm pack --dry-run

许可证

MIT。请参阅 LICENSE。