fleet #

A single source of truth for "what machines do I have access to, their capabilities, designations, and live status." Code is public-safe; the machine DATA (IPs, ssh keys, roles) stays in the private vault.

Three moving parts:

machines.json (vault, canonical) → the source of truth @jeffrey edits.
normalize-machines.mjs → enriches it into the fleet schema (adds designation, capabilities[], status, tailnet cross-refs) and writes machines.normalized.json to the vault for review — it never overwrites the canonical file.
fleet-mcp.mjs → a stdio MCP server that merges the (normalized) static registry with live tailscale status, so any agent can discover the fleet.

vault/machines.json  ──normalize-machines.mjs──▶  vault/machines.normalized.json
                                                          │
                          tailscale status --json  ──────▶ fleet-mcp.mjs  ──▶ agents

Schema (proposed) #

Each machine gains, on top of its existing fields:

field	meaning
`name`	canonical registry key (often == tailnet short name)
`designation`	ONE primary fleet role (see below)
`capabilities[]`	composable tags: `gpu`, `cuda`, `mlx`, `unreal`, `docker`, `macos-automation`, `screen-capture`, `chromium-pool`, `ffmpeg-render`, `always-on`, `git-remote`, `mongodb`, `redis`, `mail`, `web-host`, `build-macos`, `build-ios`, `tailnet-api`, `art-display`
`tailscale`	`{ name, ip }` — magic-DNS short name for live-status matching
`status`	`{ source, key }` — how liveness resolves (`tailscale` / `http` / `lan` / `none`)
`hardware`	`{ model, chip, cores, memory, gpu }`
`fleetRole`	one-line human summary

Designations: agent-endpoint (hosts a hermes gateway + identity) · compute-node (headless capability provider over HTTP MCP on the tailnet) · control (human/agent-driven author box, holds git auth) · build (build/CI) · service (db/session/mail/web) · display · legacy.

The full vocabulary with descriptions lives in the _schema block of the normalized file and is queryable via the fleet_designations MCP tool.

Usage #

# regenerate the review file after editing the vault registry
node toolchain/fleet/normalize-machines.mjs

# CLI smoke test (same code the MCP runs)
node toolchain/fleet/fleet-mcp.mjs list
node toolchain/fleet/fleet-mcp.mjs find gpu
node toolchain/fleet/fleet-mcp.mjs machine macbook-pro-clam

Data path is resolved in order: $FLEET_MACHINES → vault machines.normalized.json → vault machines.json. Tailscale binary: $TAILSCALE_BIN → /Applications/Tailscale.app/... → tailscale on PATH.

Register as an MCP #

Claude Code (~/aesthetic-computer/.mcp.json, alongside frame/puppet):

"fleet": {
  "type": "stdio",
  "command": "node",
  "args": ["toolchain/fleet/fleet-mcp.mjs"]
}

hermes (config.yaml), same stdio contract:

mcpServers:
  fleet:
    command: node
    args: ["toolchain/fleet/fleet-mcp.mjs"]
    # env:
    #   FLEET_MACHINES: /path/to/machines.normalized.json

Dashboard design note #

See DASHBOARD.md for the fleet/auth dashboard design + recommendation.