Skip to main content
ClawQL

Deployment

Production-style setups run one service: clawql-mcp-http exposes MCP at /mcp and GraphQL at /graphql on the same port.

Streamable HTTP

From the published package:

PORT=8080 npx -p clawql-mcp clawql-mcp-http

Default local MCP endpoint (make local-k8s-up + values-docker-desktop.yaml): http://clawql-mcp.localhost/mcp (Ingress — prod parity), health /healthz, Prometheus scrape GET /metrics (prom-client OpenMetrics). Compose / npx still often use http://localhost:8080/mcp. Configure the client with url, not command.

Native GraphQL/gRPC metrics: scrape GET /metrics for OpenMetrics counters/gauges per sourceLabel. Optionally set CLAWQL_HEALTHZ_NATIVE_PROTOCOL_METRICS=1 so GET /healthz also includes the same snapshot as JSON (nativeProtocolMetrics). Disable the metrics route only if required: CLAWQL_DISABLE_HTTP_METRICS=1. Repo: docs/readme/deployment.md (#191).

Private tailnet: if you are new to Tailscale / Headscale, start with Tailscale & Headscale (same content as docs/deployment/tailscale-and-headscale-for-clawql.md). For managed Tailscale, use HTTPS MagicDNS (for example https://your-machine.your-tailnet.ts.net/mcp) or Serve; for self-hosted Headscale and *.clawql.local, use runbook docs/deployment/headscale-tailnet.md (#206) and ACL starter docs/deployment/headscale-acls-clawql.hujson (#213). Keep CLAWQL_MCP_URL in env and reference ${env:CLAWQL_MCP_URL} in mcp.json; align PAPERLESS_BASE_URL, ONYX_BASE_URL, CLAWQL_SANDBOX_BRIDGE_URL, and similar with the same network. Short form: docs/readme/deployment.md (#211).

Optional gRPC (protobuf MCP)

The same registered tools (including CallTool) can be exposed over gRPC in the same process as Streamable HTTP. Set ENABLE_GRPC=1; the server listens on GRPC_PORT (default 50051) using the mcp-grpc-transport package (model_context_protocol.Mcp, grpc.health.v1.Health, optional reflection). Clients must send mcp-protocol-version metadata on protobuf RPCs. Invoking from the shell: packages/mcp-grpc-transport README — Testing and invoking MCP over gRPC. On Kubernetes, the clawql-mcp-http Service publishes HTTP and gRPC (50051) so agents can reach localhost:50051 (or the LoadBalancer IP) without port-forward when gRPC is enabled—see Kubernetes and docs/deployment/deploy-k8s.md.

Docker

The repo ships a multi-stage Distroless image (docker/README.md) with dist/, bin/, and providers/ for offline bundled specs. Build, run, and compose examples:

github.com/danielsmithdevelopment/ClawQL/blob/main/docker/README.md

Security and supply chain

Golden image (containers): end-to-end narrative—repo gates → single BuildKit OCI export per image → Trivy on that layout → skopeo copy (same bytes) → Cosign keyless → imagetools promotion of latest / nightly — is in docs/security/golden-image-pipeline.md. Kubernetes: the Helm chart defaults Kyverno verifyImages for the ClawQL GHCR images (MCP, website, dashboard, and bridge) (Security, image-signature-enforcement.md). npm packages use a separate flow: npm-supply-chain.md. Operator cosign verify commands: docker/README.md.

Cloud Run

One-shot script (sets project/region via env):

PROJECT_ID="your-project-id" \
REGION="us-central1" \
bash scripts/deploy/deploy-cloud-run.sh

Or with Make:

PROJECT_ID="your-project-id" REGION="us-central1" make deploy-cloud-run

After deploy, agents use https://<mcp-service-url>/mcp. Full options: docs/deployment/deploy-cloud-run.md.

Kubernetes

Local MCP on Kubernetes (namespace clawql, Ingress http://clawql-mcp.localhost/mcp, signed GHCR images, Kyverno installed by make local-k8s-up) is covered on Kubernetes.

Bundled dashboard deployment and Vault-sync behavior is covered on Dashboard on Kubernetes.

Optional Istio + observability lab (Prometheus, Grafana, Grafana Tempo, Kiali, OpenTelemetry Collector): beginner-oriented walkthrough on Docker Desktop: Istio & observability; canonical copy in docs/deployment/docker-desktop-istio-observability.md.

For remote clusters, use Kustomize overlays with image tag injection:

ENV=dev IMAGE=us-central1-docker.pkg.dev/<project>/<repo>/clawql-mcp TAG=<tag> make deploy-k8s

Or install with Helm from charts/clawql-mcp: Helm and docs/deployment/helm.md.

Optional NATS JetStream (event backbone for agents / Ouroboros / edge sync): NATS JetStream (#127).

OpenClaw (gateway / MCP host for ClawQL): full guide OpenClaw + ClawQL · docs/openclaw/using-openclaw-with-clawql.md; bootstrap docs/openclaw/clawql-bootstrap.md (#226); IDP skill profile docs/openclaw/openclaw-idp-skill-profile.md (#227); umbrella #128.

Human-in-the-loop (Label Studio): optional hitl_enqueue_label_studio when CLAWQL_ENABLE_HITL_LABEL_STUDIO=1 — enqueue review tasks via the Label Studio import API and expose POST /hitl/label-studio/webhook for annotation callbacks (#228). Website overview HITL — Label Studio; full operator guide docs/mcp/hitl-label-studio.md. Helm: enableHitlLabelStudio in docs/deployment/helm.md.

Details: docs/deployment/deploy-k8s.md. Extended container and manifest notes: docker/README.md.