Skip to main content
ClawQL

Tailscale and Headscale for ClawQL

Private tailnet = WireGuard mesh + DNS so clawql-mcp-http at /mcp and your execute targets (Ollama, Paperless, Onyx, …) stay off the public internet. This page is the on-site walkthrough; the canonical copy (for PRs and deep links) is docs/deployment/tailscale-and-headscale-for-clawql.md.

Why bother?

  • MCP clients need a real url (not only localhost if the IDE runs elsewhere).
  • execute follows BASE_URL / spec servers. Wrong URLs send traffic out to the public internet.
  • A tailnet gives stable 100.x addresses and MagicDNS names for members only.

Concepts (quick)

TermMeaning
Tailscale clientSoftware on each device; registers with the control plane.
TailnetYour private mesh of machines + policy.
Control planeTailscale Inc. (managed) or Headscale (you self-host).
MagicDNSNames like *.ts.net or *.clawql.local → tailnet IP.
ACLWho may reach which ports; tighten after bootstrap (#213).

Primers: What is Tailscale? · MagicDNS · ACLs.

Managed Tailscale vs Headscale

Managed TailscaleHeadscale (self-hosted)
OperatorTailscale admin consoleYour headscale server + CLI
Names*.ts.netYou pick MagicDNS base (repo pattern clawql.local)
Pick whenFastest path, less infraControl plane ownership / residency

Issue context: #211. Shorter env notes: docs/readme/deployment.md — Private tailnet.

  1. Install Tailscale on the MCP host and every operator laptop.
  2. Sign in so all machines join the same tailnet (admin console → Machines).
  3. Enable MagicDNS so each host gets a stable *.ts.net (or your tailnet’s) name — MagicDNS KB.
  4. Expose MCP with HTTPS — e.g. Tailscale Serve proxying to http://127.0.0.1:8080 so clients use https://…/mcp.
  5. Cursor / MCP: set CLAWQL_MCP_URL and use ${env:CLAWQL_MCP_URL} in mcp.json (Cursor env interpolation).
  6. Workflows: CLAWQL_MCP_URL is for scripts like workflow:complex-release-stack:mcp (polls /healthz); the MCP process itself does not read it.
  7. Provider URLs: align PAPERLESS_BASE_URL, ONYX_BASE_URL, TIKA_BASE_URL, CLAWQL_SANDBOX_BRIDGE_URL, CLAWQL_API_BASE_URL, CLAWQL_GRAPHQL_*, etc., to tailnet hostnames — see .env.example.

Smoke test: from another tailnet device, curl your /healthz, then confirm listTools / a safe execute in the client.

Part B — Headscale (self-hosted control plane)

Full ops runbook: docs/deployment/headscale-tailnet.md (#206).

  1. Run Headscale on a small always-on host; configure server_url, TLS, persistence, backups.
  2. Enable MagicDNS with base_domain clawql.local (or your choice).
  3. Enroll nodes with tailscale up --login-server https://… (Headscale docs).
  4. After the mesh works, replace permissive ACLs — starter headscale-acls-clawql.hujson (#213) and ACL section.

Example URLs: http://mac-mini.clawql.local:8080/mcp, /healthz — same CLAWQL_MCP_URL / mcp.json hygiene as Part A.

Kubernetes *.clawql.local ≠ Headscale MagicDNS (same suffix)

Helm / Ingress examples use something.clawql.local resolved by cluster DNS (or hosts → cluster IP). Headscale *.clawql.local resolves on enrolled Tailscale nodes only when Headscale MagicDNS is set up. Same string, different resolvers — see docs/clawql-ecosystem.md.

Security checklist

  • Never commit live pre-auth keys, MCP bearer tokens, or bridge secrets.
  • Prefer HTTPS for MCP where clients expect TLS; restrict host firewalls to 100.64.0.0/10 or ACL tags when binding 0.0.0.0.
  • Treat public MCP as a separate product decision — docs/enterprise-mcp-tools.md.

HIPAA, SOC 2, GDPR / CCPA (how this pattern helps)

Not legal or compliance advice. Frameworks need your BAAs, DPAs, SCCs, policies, logging, DPIAs, and attestation—a tailnet is one technical layer.

  • Segmentation & least privilege: MCP and execute targets stay on private mesh paths with ACLs, instead of a default-public listener—supports access-control narratives for SOC 2 (e.g. CC6) and reasonable security expectations (CCPA / CPRA).
  • Encryption in transit: WireGuard between nodes; add HTTPS (Serve / proxy) for app-layer TLS where required—relevant to HIPAA Security Rule transmission safeguards and GDPR Art. 32 when documented as part of TOMs.
  • Vendors & residency: Managed Tailscale is a subprocessor (metadata, control plane)—put it in your DPA / transfer analysis (GDPR Ch. V). Headscale can support in-region control-plane ownership if you run it securely.
  • HIPAA: supports technical safeguards only alongside administrative/physical controls, BAAs, minimum necessary, and breach processes—especially if tools can reach ePHI systems.
  • Evidence: document data flows (agent → MCP → each BASE_URL), ACL owners, and what logs retain—pair with app audit / SIEM as in enterprise-mcp-tools.md.

Full tables, auditor checklist, and disclaimers: tailscale-and-headscale-for-clawql.md § Regulatory and compliance.

Troubleshooting

  • No DNS → MagicDNS off, wrong domain, or client not using tailnet DNS.
  • Timeout → ACL too tight, UDP mesh blocked, or wrong port.
  • Only server can use MCP → laptops still pointed at localhost — switch to MagicDNS / Serve URL.
  • execute still public → BASE_URL not repointed to tailnet hostnames.

Next steps

Was this page helpful?