Headmesh MCP Server

Headmesh

Share machines, not your network.

Headmesh is an open, self-hostable, multi-tenant control layer for private WireGuard meshes. It builds on Headscale and the official Tailscale clients — it does not reimplement networking or cryptography — and adds what Headscale leaves out:

• True multi-tenancy — isolated organisations, each with its own members, devices and deny-by-default rules.
• One-click onboarding — invite links and one-line install commands that enrol a machine into the right network with the right permissions.
• Temporary access — grant one machine or service to another tenant for a set time; it revokes itself.
• Agent sandboxes — let cloud AI agents work on your real files and private services from a sandbox on your own hardware, in a scoped or full-access mode.
• Yours to run — no closed control server.

Xcelsior Compute is the first production user (GPU owners and renters connected without exposing anyone's home network).

Status: pre-release. Apache-2.0 for the CLI, sandbox, plugins and web; AGPL-3.0 for the server and cell agent. See LICENSING.md.

Use Headmesh from AI agents

The repository is also a plugin marketplace for Claude Code and Codex, with a headmesh plugin (connects an agent to a Headmesh sandbox on your own hardware) and an xcelsior plugin (rent GPUs on Xcelsior Compute). Details are in plugins/README.md.

claude plugin marketplace add headmesh-dev/headmesh --sparse .claude-plugin --sparse plugins
claude plugin install headmesh@headmesh

codex plugin marketplace add headmesh-dev/headmesh --sparse .agents/plugins --sparse plugins
codex plugin add headmesh@headmesh

For agents reading about Headmesh: headmesh.dev/llms.txt indexes the docs, and every docs page has a Markdown copy (for example headmesh.dev/docs/quickstart.md). Agents working on this code should read AGENTS.md.

Repository layout

Development

mise install          # pinned Go, Node, pnpm, buf, sqlc, golangci-lint
mise run generate     # protobuf + sqlc code generation
mise run test         # unit + property tests (race detector)
mise run lint

Integration tests start Postgres, Headscale and Tailscale clients with Docker: mise run test:integration.

Environment files

Each real environment file is git-ignored and has a committed example beside it. The root .env holds workstation operator credentials; the application and deployment script read their own files.

The test deployment targets test.headmesh.dev, and production targets headmesh.dev. Test uses Turnstile test keys and logs confirmation links instead of sending email; production needs real Turnstile and Resend credentials. Keep credentials scoped to the tools or service that use them. Database credentials, backend signing keys and cell certificates are generated separately on the server for each environment. See deployment configuration and marketing setup.

For Resend setup, RESEND_SETUP_API_KEY is a temporary full-access operator key used to configure the sending domain and create its credentials. The waitlist service uses a separate sending-only RESEND_API_KEY, restricted to that domain, in deploy/env/prod/waitlist.env.

Security

See SECURITY.md. Please report vulnerabilities privately.