Install ThinkWatch on Kubernetes with Helm and Localtonet

Understand the ThinkWatch deployment and exposure plan

ThinkWatch Enterprise provides a centralized gateway for model requests and MCP tool calls. Its documented capabilities include authentication, authorization, rate limiting, audit logging, cost accounting, routing, format conversion, outbound data inspection, and per-user identity for MCP calls. The deployment contains two endpoints with different audiences: the client-facing gateway on port 3000 and the administrative console on port 3001.

That distinction should shape the network design. AI clients and SDKs need a route to the gateway, but ordinary remote clients do not need direct access to the console. The safe scope for this guide is therefore narrow: deploy ThinkWatch, verify that Kubernetes is running it, make the gateway reachable from the machine running our client, and create an HTTP tunnel to that gateway only. Port 3001 is deliberately excluded from the public tunnel.

Prepare the Kubernetes and Helm environment

The documented installation path assumes an existing Kubernetes environment and a workstation or administration host that can operate it. Before deploying, confirm that the machine from which you will run the commands has Git, GNU Make or a compatible make implementation, Helm, and kubectl. Your current Kubernetes context must point to the intended cluster, and your identity must have permission to create a namespace and install the chart resources.

The available project evidence does not establish minimum Kubernetes, Helm, Docker, operating-system, CPU, memory, or storage versions. It also does not provide a universal list of required configuration values, secrets, ingress settings, or storage classes. We therefore cannot responsibly prescribe version numbers or cluster sizing. Validate those details against the ThinkWatch release and chart you intend to deploy, especially in a production environment.

Confirm the required command-line tools

Run the following checks from the administration host. They do not enforce unsupported version assumptions. They simply confirm that each tool is installed and callable.

git --version
make --version
helm version
kubectl version --client

Next, confirm which cluster and namespace context kubectl will use. This is important because Helm acts on the selected Kubernetes context unless you explicitly choose another one through supported Helm or Kubernetes configuration.

kubectl config current-context
kubectl cluster-info

If the context is wrong, stop before installation and select the intended context using your organization's established Kubernetes procedure. The correct context name is environment-specific and must not be guessed.

Check deployment permissions

The release-specific Helm example creates a namespace named thinkwatch. You can ask Kubernetes whether your current identity is permitted to create namespaces:

kubectl auth can-i create namespaces

Chart resources may require additional permissions. Required resource types depend on the current chart, so review your cluster's authorization policy and the rendered chart before production installation. A successful namespace permission check alone does not guarantee permission to create every chart resource.

Decide how the Localtonet client will reach the gateway

The Localtonet client must run on a device that can reach the local target. For a Kubernetes deployment, there are several possible network designs, but this guide uses a conservative local port-forward pattern. You run kubectl port-forward on an administration host, bind the gateway to 127.0.0.1:3000, and run our client on that same host.

This approach avoids guessing a cloud load balancer, ingress controller, node address, or cluster-specific service route. It also keeps the Kubernetes service from needing its own direct public exposure. The port-forward process must remain active for the Localtonet tunnel to reach the gateway.

Install ThinkWatch on Kubernetes with Helm

ThinkWatch documents make helm-deploy as its Kubernetes deployment command. This is the preferred path here because it uses the deployment automation maintained in the repository. A separate direct Helm example was published with the 3.8.1 release, which is useful when reproducing that specific packaged chart.

git clone https://github.com/ThinkWatchProject/ThinkWatch.git
cd ThinkWatch
make helm-deploy

The command above deliberately does not add undocumented flags. Before running it in a production cluster, inspect what the Make target invokes and how the checked-out revision supplies chart values. Repository automation can evolve, so reviewing the target is part of operating a pinned, auditable deployment.

Alternative: reproduce the published 3.8.1 Helm installation

The ThinkWatch 3.8.1 release published a chart package named think-watch-3.8.1.tgz and the following installation command. Use it only after obtaining and verifying that release asset through your normal artifact-control process and placing it in the current directory:

helm install think-watch ./think-watch-3.8.1.tgz \
  --namespace thinkwatch \
  --create-namespace

This installs a Helm release named think-watch into a namespace named thinkwatch, creating that namespace if it does not already exist. It does not prove that version 3.8.1 is suitable for your current environment. The release also published server and web container images tagged 3.8.1, but image selection should be left to the matching chart rather than manually mixing chart and image versions without documented compatibility.

Verify the ThinkWatch Kubernetes deployment

A completed Helm command is only the first verification point. It confirms that Helm submitted resources, not that every workload is healthy or that the gateway is configured for useful traffic. Verify the release, namespace, pods, services, and recent events before creating any public route.

Confirm the namespace and Helm release

If the deployment used the documented thinkwatch namespace, list its Helm releases and Kubernetes resources:

kubectl get namespace thinkwatch
helm list --namespace thinkwatch
kubectl get all --namespace thinkwatch

The Helm list should include the installed release. The resource list reveals the actual workload and service names created by your chart version. Use those names in subsequent commands rather than assuming that a Helm release name, deployment name, pod name, and service name are identical.

Watch pod readiness

kubectl get pods --namespace thinkwatch --watch

Wait for the expected pods to reach their ready state. Exit the watch with Ctrl+C. A pod that is running but not ready may still be failing a readiness check or waiting on a dependency. A completed installation should not be considered healthy solely because the pod phase says Running.

Inspect services and endpoints

kubectl get services --namespace thinkwatch
kubectl get endpoints --namespace thinkwatch

Identify the service that routes to the client-facing ThinkWatch gateway. Confirm its reported service port and that it has backing endpoints. The official reader-facing information identifies the gateway on port 3000, but the chart's service port and resource name should still be read from the deployed release. Kubernetes charts can map a service port to a different target port, and this guide does not guess that mapping.

Inspect failures without guessing resource names

If a pod is not ready, copy its actual name from kubectl get pods and use it in the following commands:

kubectl describe pod --namespace thinkwatch <pod-name>
kubectl logs --namespace thinkwatch <pod-name>

For a pod with multiple containers, kubectl logs may ask you to select one. Obtain the real container names first:

kubectl get pod --namespace thinkwatch <pod-name> \
  -o jsonpath='{.spec.containers[*].name}'

Then request logs for the relevant container:

kubectl logs --namespace thinkwatch <pod-name> \
  --container <container-name>

Namespace events can reveal scheduling, image-pull, volume, readiness, and admission failures:

kubectl get events --namespace thinkwatch \
  --sort-by=.metadata.creationTimestamp

Create and test a local path to the gateway

Before involving Localtonet, prove that the machine running our client can reach ThinkWatch locally. This isolates Kubernetes and application problems from tunnel configuration problems. A local Kubernetes port-forward is useful because it creates a loopback listener without requiring a public ingress or load balancer.

Find the gateway service and its port

kubectl get services --namespace thinkwatch

Locate the service associated with the client-facing gateway, not the administrative console. Record the service name and its reported gateway service port. The placeholders in the next command are intentional because service naming and service-port mapping are chart-specific.

Forward the gateway to local port 3000

kubectl port-forward --namespace thinkwatch \
  service/<gateway-service-name> \
  3000:<reported-gateway-service-port>

Keep this command running. It creates a listener at 127.0.0.1:3000 by default and forwards traffic through the Kubernetes API connection to the selected service. If local port 3000 is already occupied, stop the conflicting process or choose another unused local port. When choosing another port, use that same local port as the Localtonet HTTP target later.

Test transport from a second terminal

curl -i http://127.0.0.1:3000/

Do not assume that the root path must return a particular status code or response body. The supplied evidence does not define a public health-check path. An authentication response, method error, or route-not-found response can still demonstrate that an HTTP server answered. A connection-refused or timeout result indicates that the local listener or forwarding path is not working.

If your actual gateway test requires authentication, a specific API path, or a request body, use the endpoint and credentials created through your ThinkWatch configuration. Do not place real API keys in shell history, screenshots, article examples, or support messages.

Expose the ThinkWatch gateway with a Localtonet HTTP tunnel

Once http://127.0.0.1:3000 is responding on the machine that will run our client, the Localtonet part is straightforward. The client establishes an outbound connection to a Localtonet relay server. The resulting HTTP tunnel provides a public HTTPS address without inbound router port forwarding, a public IP address, VPN setup, or firewall changes.

The tunnel is available only while the selected client device is connected and the tunnel is running. In this Kubernetes port-forward design, the kubectl port-forward process must also remain active. If either process stops, the public endpoint can no longer reach ThinkWatch.

HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. Each serves the target at a public HTTPS address. Availability can vary by plan and current product configuration. Custom-domain DNS requirements should be checked against the current Localtonet documentation before changing DNS.

For the current dashboard workflow and available options, consult our HTTP tunnel documentation.

Verify the complete request path

Test in layers so a failure has a clear boundary:

1. Confirm the ThinkWatch pods and services are healthy in Kubernetes.
2. Confirm the Kubernetes port-forward process is still running.
3. Confirm http://127.0.0.1:3000 answers on the Localtonet client device.
4. Confirm the Localtonet device is connected.
5. Confirm the HTTP tunnel is started rather than merely created.
6. Send a request to the assigned public HTTPS address.
7. Check ThinkWatch logs and audit information to confirm that the expected authenticated request arrived.

This layered sequence prevents a Kubernetes problem from being misdiagnosed as a tunnel problem. It also distinguishes transport success from authorization success. For example, an HTTP authentication rejection proves more about connectivity than a timeout, even though the request itself was not authorized.

Operate and update the deployment safely

A self-hosted gateway becomes part of the request path for AI and MCP clients, so routine operations deserve the same discipline as the initial installation. Track the deployed chart version, container image versions, configuration revision, secret rotation process, and the identity of the Localtonet device running the public route.

Keep the port-forward supervised

The port-forward command is a foreground process. Closing its terminal, losing Kubernetes API connectivity, or restarting the administration host breaks the local target. For a temporary test or controlled integration, that behavior is useful and easy to understand. For a durable production design, use an organization-approved process supervisor or a carefully designed private network path from the Localtonet client to the gateway service.

Do not blindly expose a Kubernetes service as a public load balancer merely to avoid the port-forward. That would create a second public access path and may undermine the purpose of using one controlled tunnel. Any persistent alternative should preserve the separation between the public gateway and private console.

Monitor both service layers

Monitor Kubernetes workload health and ThinkWatch request behavior separately. Kubernetes tells you whether pods, services, endpoints, and volumes are functioning. ThinkWatch provides application-level information about requests, routing, retries or failover, metering, policy decisions, and audit activity when those features are configured.

Localtonet also has its own lifecycle. A tunnel can be created but stopped, or the selected device can be disconnected. Platform-wide Token/Tunnel webhooks are available for Connected and Disconnected changes in a selected Token Group. They send a JSON body containing Id, ActionDate, Type, and Status. These connectivity webhooks are separate from application request logs and should not be interpreted as proof that ThinkWatch successfully processed a request.

Plan upgrades before applying them

Review release notes between the installed and target versions. Gateway behavior can change in ways that affect request inspection and policy outcomes. For example, the published ThinkWatch 3.8.1 release changed outbound redaction so that it searches written request text without modifying identifiers or other protocol values. It also noted that fields outside recognized written text can pass upstream as written, while stored-body redaction behavior remains separate.

That kind of change is operationally important. Test representative AI API and MCP traffic in a non-production environment, verify policy behavior, preserve a rollback path, and avoid mixing a chart from one release with container images from another unless compatibility is explicitly documented.

Stop access cleanly

When remote access is no longer required, stop the Localtonet tunnel. If the port-forward was created solely for the tunnel, terminate that process too. Deleting the Kubernetes deployment is a separate decision and is not required merely to disable public access.

Troubleshoot installation and remote-access failures

The make helm-deploy command is unavailable or fails immediately

Confirm that you are in the repository root and that the checked-out revision contains the documented Make target. Verify that make, Helm, and kubectl are callable. Then inspect the Makefile to see the exact underlying command for that revision. Do not substitute guessed chart paths or values.

Helm reports a namespace or permission error

Recheck the active Kubernetes context and your authorization. The published 3.8.1 example creates the thinkwatch namespace, which requires suitable cluster permission. In a restricted environment, ask the cluster administrator to create the namespace and grant the precise permissions required by the reviewed chart.

A pod remains pending

Use kubectl describe pod and namespace events. Common Kubernetes-level categories include unsatisfied scheduling requirements, unavailable persistent storage, admission-policy rejection, and resource constraints. The exact correction depends on the event message and the chart's documented requirements. Do not guess a storage class or weaken admission controls simply to force scheduling.

A pod enters an image-pull failure state

Inspect the pod description for the exact registry, image tag, and registry response. Confirm network access and any registry authentication required by your environment. Keep chart and image versions aligned. The evidence confirms published 3.8.1 images, but it does not justify changing an arbitrary release to those tags.

The service has no endpoints

Compare the service selector with pod labels and check pod readiness. A service without endpoints cannot forward traffic, even if the service object exists. Correct the underlying workload or chart configuration before creating a tunnel.

The port-forward reports connection refused

Confirm that you selected the gateway service and used the service port reported by Kubernetes. Verify that the service has endpoints and that the relevant pods are ready. If local port 3000 is already in use, either stop the conflicting process or choose a different local port and use that same port in the Localtonet target.

Local access works, but the public URL does not

Confirm that the port-forward is still active, our client is connected, the HTTP tunnel is started, and the tunnel target exactly matches the working local listener. Creating the tunnel alone is not enough. Also confirm that you are using the currently assigned public address rather than an old address from a stopped or deleted tunnel.

The public endpoint returns 401 or 403

An authorization response usually means the network path is functioning and the application rejected the request. Check the ThinkWatch client credential, role, API key scope, tool permission, and relevant policy. Do not disable authentication to turn an authorization failure into a successful response.

The public endpoint returns 404

Confirm that the client is requesting a valid ThinkWatch gateway path. The root path is useful only as a basic transport probe because the supplied evidence does not define it as a health endpoint. Use the path documented for the client integration and installed ThinkWatch release.

Requests reach ThinkWatch but upstream model calls fail

That result is beyond tunnel connectivity. Inspect ThinkWatch's routing, upstream configuration, credentials, provider response, budgets, rate limits, and policy decisions. The gateway can be reachable while an upstream is unavailable or unauthorized. Keep provider credentials private when collecting logs.

The gateway works until the terminal closes

The Kubernetes port-forward process ended with the terminal. Restart it and then retest the local endpoint before checking the public endpoint. For sustained use, operate the forwarding process under an approved supervisor or build a private, persistent route that does not expose the console or Kubernetes control plane.

Frequently asked questions