Cluster Setup

Goal

Prepare a Kubernetes cluster to run tentacles.

Prerequisites

A Kubernetes cluster (EKS, GKE, AKS, k0s, k3s, kind)
kubectl configured with cluster access
helm installed
Container registry accessible from the cluster

Steps

1. Install the MCP Server

# Clone the MCP server repo
git clone git@github.com:randybias/tentacular-mcp.git

# Generate a token and install via Helm
TOKEN=$(openssl rand -hex 32)
kubectl create namespace tentacular-support
helm install tentacular-mcp ./tentacular-mcp/charts/tentacular-mcp \
  --namespace tentacular-system --create-namespace \
  --set auth.token="${TOKEN}"

Save the bearer token for CLI configuration:

mkdir -p ~/.tentacular
echo "${TOKEN}" > ~/.tentacular/mcp-token
chmod 600 ~/.tentacular/mcp-token

2. (Optional) Install gVisor

For kernel-level sandboxing:

# On each cluster node:
sudo bash deploy/gvisor/install.sh

# Apply RuntimeClass:
kubectl apply -f deploy/gvisor/runtimeclass.yaml

# Verify:
kubectl apply -f deploy/gvisor/test-pod.yaml
kubectl logs gvisor-test
kubectl delete pod gvisor-test

See gVisor Setup for details.

3. Configure the CLI

tntc configure --project \
  --registry ghcr.io/yourorg \
  --namespace tentacular-dev

Then add MCP endpoint to .tentacular/config.yaml:

environments:
  dev:
    mcp_endpoint: http://<node-ip>:30080/mcp
    mcp_token_path: ~/.tentacular/mcp-token

Save the bearer token:

echo "<your-token>" > ~/.tentacular/mcp-token

4. Validate Cluster Readiness

tntc cluster check

This validates:

MCP server connectivity
Namespace creation capability
gVisor RuntimeClass (warning if missing)
NetworkPolicy support (CNI dependent)

5. Generate Cluster Profile

tntc cluster profile --save

This creates a capability snapshot at .tentacular/envprofiles/dev.md that agents use to inform tentacle design decisions.

6. (Optional) Set Up Exoskeleton

For backing services (Postgres, NATS, RustFS), see Exoskeleton Setup.

Verification

tntc cluster check passes all checks
tntc cluster profile shows expected capabilities
tntc deploy succeeds for a simple tentacle (e.g., word-counter)
tntc audit <name> shows clean security results

Failure Modes

Failure	Cause	Resolution
`MCP server unreachable`	Wrong endpoint or server not running	Check Helm release: `helm status tentacular-mcp -n tentacular-system`
`NetworkPolicy not supported`	CNI doesn’t support it	Use a CNI with NetworkPolicy support (Calico, Cilium, kube-router)
`gVisor RuntimeClass not found`	gVisor not installed	Install gVisor or deploy with `--runtime-class ""`
`image pull error`	Registry not accessible from cluster	Check registry credentials and network access