{
  "markdown": "# Tailscale Compute MCP\n\nRun builds, tests, and benchmarks on your own remote compute node from an MCP coding agent.\n\nThe coding agent edits files on your local computer. This MCP server copies the project through `rsync` and runs a command through SSH only when the agent calls `compute_run`.\n\nThis is an independent project. It is not an official Tailscale product and is not endorsed by Tailscale Inc. Tailscale is a trademark of Tailscale Inc.\n\n## Release status\n\nThis package is a beta.\n\n- The full path has run on a Mac laptop and an Apple M4 Mac mini.\n- The server includes Linux probes and NVIDIA inventory support.\n- Linux parsing has automated coverage.\n- This release has not run on a real NVIDIA DGX Spark. Do not treat the Linux or NVIDIA result as DGX Spark validation yet.\n\n## How it works\n\n```text\nMCP coding agent\n    |\n    | local stdio\n    v\nTailscale Compute MCP\n    |\n    | rsync and SSH through the user's tailnet\n    v\nMac or Linux compute node\n```\n\nThe package runs on the local computer. No MCP service runs on the remote node. The project author does not receive your code, credentials, command output, or Tailscale traffic.\n\n## Security warning\n\n`compute_run` can run any non-interactive command with the permissions of the remote SSH user. Treat it as remote code execution.\n\n- Use a dedicated non-root account on the remote node.\n- `compute_status` reports the remote user id and warns when the SSH user is root. Run compute through a non-root user so a compromised build cannot control the whole node.\n- Command starts, artifact fetches, and successful workspace deletions are recorded in a local audit log. The log never contains environment values, standard input, or credentials.\n- Do not auto-approve command, fetch, cancel, or deletion tools.\n- Do not put passwords, SSH private keys, or Tailscale auth keys in MCP configuration.\n- Use an SSH agent or Tailscale SSH.\n- Limit access with Tailscale policy rules.\n- Review [`SECURITY.md`](SECURITY.md) before use.\n\n## Requirements\n\n### Local computer\n\n- Node.js 20 or later.\n- Tailscale connected to the same tailnet as the remote node.\n- OpenSSH client.\n- `rsync` with `--include` and `--exclude` support.\n- An MCP host that supports local stdio servers.\n\nmacOS and Linux are the supported local systems for this beta.\n\n### Remote node\n\n- Darwin or Linux.\n- Tailscale connected.\n- SSH server.\n- `rsync` available on `PATH`.\n- A known SSH host key.\n- The toolchain required by the project.\n\nThe MCP package does not need Node.js on the remote node unless the remote workload uses Node.js.\n\n## Set up a Mac mini\n\n1. Install and connect Tailscale on both Macs.\n2. On the Mac mini, open **System Settings**, select **General**, select **Sharing**, and turn on **Remote Login**.\n3. Add the local public key to the remote account:\n\n```sh\nssh-copy-id -i ~/.ssh/id_ed25519.pub user@mac-mini.example.ts.net\n```\n\n4. Verify the host key and non-interactive access:\n\n```sh\nssh user@mac-mini.example.ts.net /usr/bin/true\n```\n\n5. Check the remote tools:\n\n```sh\nssh user@mac-mini.example.ts.net '/bin/zsh -lc \"rsync --version\"'\n```\n\nA sleeping or powered-off Mac might not accept a Tailscale connection. Configure macOS network wake when required. This MCP server does not send wake packets.\n\n## Set up a Linux node\n\nInstall and connect Tailscale by using the official Tailscale instructions for your Linux distribution. Then install an SSH server and `rsync`.\n\nFor Ubuntu or Debian:\n\n```sh\nsudo apt-get update\nsudo apt-get install --yes openssh-server rsync\nsudo systemctl enable --now ssh\n```\n\nUse a standard SSH key:\n\n```sh\nssh-copy-id -i ~/.ssh/id_ed25519.pub user@compute-node.example.ts.net\nssh user@compute-node.example.ts.net /usr/bin/true\n```\n\nYou can use Tailscale SSH on supported Linux nodes instead of distributing SSH keys. Your Tailscale policy must permit both the network connection and SSH connection.\n\n## Install in an MCP host\n\nPin the package version. Do not use an unpinned package for agent command execution.\n\n### Oh My Pi (OMP)\n\nRun the safe setup command for the default OMP profile:\n\n```sh\nnpx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5 \\\n  setup omp \\\n  --host user@compute-node.example.ts.net\n```\n\nThe command prints the MCP configuration path and the fleet skill path. It\nruns the real SSH connection check before it writes a file. It then adds\n`tailscale-compute` to `~/.omp/agent/mcp.json` and installs the managed\n`tailscale-compute-fleet` skill in `~/.omp/agent/skills/`. It preserves other\nservers, pins this package version, and uses atomic file replacement.\n\nThe command does not write a file when the connection check fails. It refuses\nmalformed JSON, symbolic links, a server name with different settings, and an\nunmanaged skill with the same name.\n\nFor a named profile, manually merge the server entry into\n`~/.omp/profiles/<name>/agent/mcp.json` and install the skill in that profile's\n`skills/tailscale-compute-fleet/` directory. Keep all existing server entries:\n\n```json\n{\n  \"mcpServers\": {\n    \"tailscale-compute\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\"\n      ],\n      \"env\": {\n        \"TAILSCALE_COMPUTE_HOST\": \"user@compute-node.example.ts.net\"\n      }\n    }\n  }\n}\n```\n\nReplace the example host with the SSH user and the Tailscale IP address or\nfull MagicDNS name of your compute node.\n\nStart a new OMP session after setup. OMP then loads the server and advertises\nthe fleet skill to the agent automatically. In an existing session,\n`/mcp reload` loads the server, but the new skill becomes available in the\nnext session. Test the server after reload or restart:\n\n```text\n/mcp test tailscale-compute\n```\n\nPrint a pinned configuration for Claude Code, Cursor, Codex, or OpenCode:\n\n```sh\nnpx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5 \\\n  setup print --client <claude|cursor|codex|opencode> \\\n  --host user@compute-node.example.ts.net\n```\n\nThe Claude output is a user-scoped command. The Cursor and OpenCode outputs\nare JSON. The Codex output is TOML for `~/.codex/config.toml`. Merge JSON or\nTOML output with an existing client configuration instead of replacing\nunrelated entries.\n\n### VS Code\n\nCreate `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"tailscale-compute\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\"\n      ],\n      \"env\": {\n        \"TAILSCALE_COMPUTE_HOST\": \"user@compute-node.example.ts.net\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nCreate `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tailscale-compute\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\"\n      ],\n      \"env\": {\n        \"TAILSCALE_COMPUTE_HOST\": \"user@compute-node.example.ts.net\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```sh\nclaude mcp add --scope user \\\n  --env TAILSCALE_COMPUTE_HOST=user@compute-node.example.ts.net \\\n  --transport stdio tailscale-compute \\\n  -- npx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\n```\n\n## Check the connection\n\nRun the package outside the MCP host first:\n\n```sh\nTAILSCALE_COMPUTE_HOST=user@compute-node.example.ts.net \\\nnpx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5 --check\n```\n\nA successful check returns `kind: \"ready\"`. It also reports:\n\n- Operating system.\n- CPU architecture and model.\n- Logical processor count.\n- Memory.\n- Selected remote shell.\n- `rsync` version.\n- NVIDIA GPU inventory when `nvidia-smi` is available.\n- Live uptime, load averages, available memory, storage capacity, active durable job count, and NVIDIA memory and utilization.\n\n## MCP tools\n\n### `compute_status`\n\nChecks SSH access and reports the remote platform, hardware, and live health.\n\nInstalled GPU memory stays in `hardware.acceleratorInventory`. Current GPU\nmemory use, available memory, and utilization stay in\n`health.acceleratorUsage`.\n\n### `compute_doctor`\n\nRuns the explicit `pytorch` profile with one selected Python program on one\nrequired logical CUDA device:\n\n```json\n{\n  \"profile\": \"pytorch\",\n  \"pythonProgram\": \"/opt/project/.venv/bin/python\",\n  \"requiredDevice\": \"cuda:0\",\n  \"minimumAvailableMemoryBytes\": 24000000000\n}\n```\n\nThe selected Python program must contain PyTorch with CUDA support. The remote\nnode must also provide `nvidia-smi`. The profile reports the NVIDIA driver, the\nPyTorch CUDA runtime, optional `nvcc` compiler, cuDNN, compute capability,\navailable memory, dtype, and relevant backend flags. It runs a known\n`torch.float32` linear operation and verifies its result. It also verifies that\nthe model, input, intermediate value, and output stay on the required device. A\nmissing requirement returns `check_failed`; the profile never selects a\ndifferent GPU or falls back to the CPU.\n\nThe doctor proves only its small operation. Run the real workload and check\nits outputs before you claim application support.\n\n### `compute_workspace_status`\n\nReports the managed remote path, disk usage, last successful sync, last run\nrequest, and active durable job IDs for one local workspace.\n\n### `compute_workspace_delete`\n\nDeletes only the managed remote directory that maps to one local workspace.\nIt refuses deletion while a durable job is active. A repeated delete succeeds\nand reports `existed: false`.\n\n### `compute_run`\n\nCopies the local workspace and runs one non-interactive remote command.\n\nExample:\n\n```json\n{\n  \"program\": \"npm\",\n  \"arguments\": [\"test\"],\n  \"syncMode\": \"incremental\",\n  \"timeoutSeconds\": 900\n}\n```\n\nFor shell syntax, call a supported remote shell explicitly:\n\n```json\n{\n  \"program\": \"/bin/bash\",\n  \"arguments\": [\"-lc\", \"npm ci && npm test\"],\n  \"syncMode\": \"clean\",\n  \"timeoutSeconds\": 1800\n}\n```\n\n`compute_run` returns the remote exit code, standard output, standard error, sync time, and command time. Output is limited to protect the MCP connection. When output is too large, the result keeps its start and end and reports the omitted byte count.\n\n### Hardware requirements\n\n`compute_run` and `compute_job_start` accept an optional `requirements`\nobject. The server checks these requirements against the remote hardware\nbefore it starts the workload. It returns `kind: \"requirements_not_met\"` and\ndoes not sync or start the command when a requirement fails.\n\n```json\n{\n  \"program\": \"python\",\n  \"arguments\": [\"train.py\"],\n  \"requirements\": {\n    \"platform\": \"linux\",\n    \"architecture\": \"x86_64\",\n    \"minimumMemoryBytes\": 34359738368,\n    \"nvidia\": {\n      \"minimumDeviceCount\": 1,\n      \"minimumMemoryBytesPerDevice\": 24000000000\n    }\n  }\n}\n```\n\nThe server does not select a device and does not fall back to the CPU. The\nworkload must select and verify its required accelerator.\n\n### Durable jobs\n\n`compute_job_start` syncs the workspace and starts a detached command. It\nreturns a job ID after the remote launcher starts. The command continues when\nthe MCP client disconnects.\n\n```json\n{\n  \"program\": \"python\",\n  \"arguments\": [\"train.py\"],\n  \"syncMode\": \"incremental\",\n  \"timeoutSeconds\": 43200,\n  \"idempotencyKey\": \"training-run-2026-08-14\",\n  \"label\": \"baseline\",\n  \"artifactPaths\": [\"checkpoints/final.pt\", \"metrics/results.json\"]\n}\n```\n\n- `compute_job_status` returns `starting`, `running`, `completed`, `failed`,\n  `cancelled`, or `lost`.\n- `compute_job_logs` reads `stdout` or `stderr` from an exact byte offset. Use\n  `nextOffsetBytes` in the next call. `endOfStream` becomes true after the job\n  reaches a terminal state and the returned offset reaches the file size.\n- `compute_job_cancel` stops the remote process group. A terminal job returns\n  its existing terminal state.\n- `compute_job_list` returns a filtered, paged list with job IDs, states,\n  labels, programs, workspace paths, times, and terminal results.\n- `compute_job_delete` deletes only a terminal job. It refuses active jobs and\n  unsafe remote job directories.\n\nEach terminal job state includes output byte counts and SHA-256 digests.\n\nAn idempotency key is scoped to the target and workspace. A retry with the\nsame request returns the existing job. Reuse with a different request returns\n`idempotency_conflict`.\n\nAfter the command ends, declared artifact paths are copied into an immutable\njob snapshot. The terminal status contains the updated receipt, which records\neach regular file path, size, and SHA-256 digest. Workspace synchronization\ndoes not delete these snapshots.\n\nTerminal results classify a normal exit, signal, timeout, cancellation, lost\njob, or out-of-memory termination. The server reports out-of-memory only when\nthe process exit and Linux cgroup memory event evidence agree.\n\nSet `TAILSCALE_COMPUTE_MAX_ACTIVE_JOBS` to enforce one node-wide limit across\nall workspaces and MCP server processes that use the same remote root. Job\nadmission uses an atomic remote reservation. A full node returns `node_busy`\nwith the configured limit, active job IDs, and the number of starts that are\nstill in admission. It does not queue or start the refused job.\n\n### `compute_fetch`\n\nFetches selected files or directories from the managed remote workspace to a\nlocal destination under the local workspace.\n\n```json\n{\n  \"paths\": [\"benchmark/results.json\"],\n  \"localDestination\": \".tailscale-compute-results/latest\",\n  \"overwrite\": false\n}\n```\n\nTo fetch every declared artifact from an immutable terminal job snapshot,\ninclude its job ID and omit `paths`:\n\n```json\n{\n  \"jobId\": \"12345678-1234-4234-8234-123456789abc\",\n  \"localDestination\": \".tailscale-compute-results/baseline\",\n  \"overwrite\": false\n}\n```\n\nSet `paths` with a job ID to fetch only selected declared artifacts. The tool\nrefuses remote symbolic links, destination escapes, undeclared job artifacts,\nand an existing destination unless `overwrite` is true. It reports the size\nand SHA-256 digest of each fetched regular file. A job fetch also checks every\ndownloaded file against the immutable job receipt.\n\n### Run receipts\n\nEach run and durable job has a structured receipt. It records the run ID,\nserver version, local Git revision, command arguments, environment variable\nnames, sync mode, reported hardware, timing, result, output digests, and\nfetched artifacts. A durable receipt can also contain its label, exhaustive\ntermination result, and immutable artifact manifest. It does not record\nenvironment values, standard input, or an idempotency key. Durable jobs store\nthe receipt in the remote job directory and update it when the job reaches a\nterminal state.\n\n## Sync modes\n\n- `incremental`: Update the managed remote workspace and delete remote files that no longer exist locally.\n- `clean`: Delete only the hashed managed workspace, create it again, and copy the project.\n- `none`: Reuse the last remote snapshot without copying local files.\n\nEach local workspace maps to a stable remote directory under:\n\n```text\n.cache/tailscale-compute-mcp\n```\n\nThe server runs commands for one workspace in sequence. Different workspaces can run at the same time.\n\n`compute_workspace_status` reports `lastSyncAt: { \"kind\": \"never\" }` or\n`lastRunAt: { \"kind\": \"never\" }` until the related event occurs.\n\n## Excluded files\n\nThe sync reads `.gitignore` and `.tailscale-compute-ignore` from the workspace root. It supports blank lines, comments that start with `#`, negation that starts with `!`, and standard rsync patterns. It does not read nested ignore files. Each ignore file can be up to 64 KiB, and the server reads up to 5,000 rules across both files. It ignores a file or later rules that exceed these limits.\n\n```text\n.git/\n.env\n.env.*\n.npmrc\n.pypirc\n.ssh/\n.aws/\n.gnupg/\n.git-credentials\n.netrc\n*_history\n.curlrc\n.wgetrc\n*.pem\n*.key\n*.p12\n*.pfx\n*.secret\nsecrets/\nnode_modules/\n.venv/\nvenv/\ntarget/\n__pycache__/\n.next/cache/\n```\n\nThe fixed exclusions above have priority. An ignore-file negation cannot include one of these files.\n\nAdd project-specific secrets and large outputs to `.tailscale-compute-ignore`.\n\nIgnored files are not copied. If a required file is ignored, create it on the remote node or provide its value through an explicit `compute_run.environment` entry. Remember that tool arguments are visible to the MCP host and model.\n\n## Configuration\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `TAILSCALE_COMPUTE_HOST` | Yes | None | SSH user and direct Tailscale IP address or full MagicDNS name. |\n| `TAILSCALE_COMPUTE_LOCAL_ROOT` | No | MCP process directory | Absolute local project path. |\n| `TAILSCALE_COMPUTE_REMOTE_ROOT` | No | `.cache/tailscale-compute-mcp` | Managed remote workspace root. |\n| `TAILSCALE_COMPUTE_REMOTE_SHELL` | No | `auto` | `auto`, `/bin/sh`, `/bin/bash`, or `/bin/zsh`. |\n| `TAILSCALE_COMPUTE_CONNECT_TIMEOUT_SECONDS` | No | `10` | SSH connection timeout from 1 through 60 seconds. |\n| `TAILSCALE_COMPUTE_MAX_ACTIVE_JOBS` | No | No limit | Node-wide durable job limit from 1 through 1024. |\n| `TAILSCALE_COMPUTE_AUDIT_LOG` | No | `~/.config/tailscale-compute-mcp/compute-audit.log` | Local audit log path for `compute_run` records. |\n\nAutomatic shell selection uses `/bin/zsh` on Darwin. It uses `/bin/bash` on Linux when available and `/bin/sh` otherwise.\n\n## Multiple compute nodes\n\nFor OMP, run setup once for each node and give each server a unique name:\n\n```sh\nnpx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5 \\\n  setup omp \\\n  --host developer@first-mini.example.ts.net \\\n  --name compute-mac-mini-1\n\nnpx -y @dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5 \\\n  setup omp \\\n  --host developer@second-mini.example.ts.net \\\n  --name compute-mac-mini-2\n```\n\nEach command checks its node and preserves the other named servers. The first\ncommand installs the fleet skill. Later commands reuse or update that managed\nskill. Start a new OMP session after the last command.\n\nFor other MCP clients, register the package more than once with a different\nname and host. Keep one target per MCP server instance.\n\n```json\n{\n  \"mcpServers\": {\n    \"compute-mac-mini\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\"],\n      \"env\": {\n        \"TAILSCALE_COMPUTE_HOST\": \"developer@mac-mini.example.ts.net\"\n      }\n    },\n    \"compute-linux\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dylantirandaz/tailscale-compute-mcp@0.1.0-beta.5\"],\n      \"env\": {\n        \"TAILSCALE_COMPUTE_HOST\": \"developer@linux-node.example.ts.net\",\n        \"TAILSCALE_COMPUTE_REMOTE_SHELL\": \"/bin/bash\"\n      }\n    }\n  }\n}\n```\n\n### Agent-controlled workflows\n\nFor independent work, let the agent query `compute_status` and\n`compute_job_list` on each named MCP server. The agent can select an eligible\nnode by platform, architecture, hardware requirements, active-job count, and\nload. A retry must use the same server, idempotency key, and request data.\nArtifacts remain owned by the selected node and must move through\n`compute_fetch` with receipt hash verification.\n\nThe package does not include a fleet scheduler or hidden queue. It also does\nnot turn an ordinary command into a distributed program. A program can use\nseveral nodes only when the project declares a distributed runtime and launch\ncommand, such as MLX distributed, Ray, or MPI. Synchronize the same workspace\nrevision and runtime version to every node before launch. Record every node\nrole and job ID, and verify every worker state during cancellation or cleanup.\n\nA Thunderbolt cable supplies a possible data-plane network between Macs. It\ndoes not combine their CPU, GPU, or unified memory. Keep MCP control\nconnections on Tailscale and use Thunderbolt addresses only through the\ndeclared runtime configuration.\n\nMLX provides `mlx.launch` for SSH-connected hosts, a TCP or Thunderbolt ring\nbackend, and JACCL for supported Thunderbolt RDMA systems. Use the\n[official MLX distributed guide](https://ml-explore.github.io/mlx/build/html/usage/distributed.html)\nfor its host-file, topology, operating-system, and RDMA requirements. A\ndistributed validation must check the world size, rank placement, backend,\ndevice placement, and a result that depends on every rank.\n\n## NVIDIA workloads\n\n`compute_status` reports NVIDIA devices through `nvidia-smi`. This inventory\ndoes not prove that a workload used a GPU. `compute_doctor` proves one small\nPyTorch operation and exact CUDA placement on the selected device, but it does\nnot prove an application workload.\n\nA GPU workload must select the intended device, verify the placement of its\nmodel, inputs, computation, and outputs, and check a meaningful result. The\nserver does not fall back to the CPU on behalf of a remote command.\n\n## Development\n\n```sh\nnpm ci\nnpm run check\n```\n\nRun a connection check against a real remote node:\n\n```sh\nTAILSCALE_COMPUTE_HOST=user@100.64.0.1 node dist/main.js --check\n```\n\nTest the package contents before release:\n\n```sh\nnpm pack --dry-run\n```\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n",
  "bytes": 20862,
  "sha": "da26cd3680b0e73ae085da83bd15d70d7e03ca957d10d7d131f8b3a545bdfd55",
  "repo_slug": "dylantirandaz/tailscale-compute-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dylantirandaz_tailscale_comput_176edc54/readme"
}