Installation

Web installer (recommended)

The interactive installer handles prerequisites, prompts for required values, and runs helm install for you.

curl -fsSL https://kubeclaw.ai/install.sh | bash

Homebrew CLI

Install the kubeclaw CLI via Homebrew, then run the guided installer.

brew install iMerica/kubeclaw/kubeclaw

kubeclaw install

The CLI provides the same guided experience as the web installer, plus commands for upgrading and managing your cluster.

Helm (advanced)

If you prefer to manage Helm directly, install from the OCI artifact.

helm install kubeclaw oci://ghcr.io/imerica/kubeclaw \
  --version 0.1.0 \
  --namespace kubeclaw \
  --create-namespace \
  --set secret.data.OPENCLAW_GATEWAY_TOKEN=change-me

When default chart toggles are enabled, three values are required:

Using a values file

For anything beyond simple key/value overrides, use a values file. This is especially important for config.desired, which contains nested JSON that --set cannot handle:

# kubeclaw-values.yaml
secret:
  data:
    OPENCLAW_GATEWAY_TOKEN: "my-strong-token"
    OPENAI_API_KEY: "sk-..."

litellm:
  masterkey: "sk-my-litellm-key"

tailscale:
  ssh:
    authKey: "tskey-auth-..."

helm install kubeclaw oci://ghcr.io/imerica/kubeclaw \
  --namespace kubeclaw --create-namespace \
  -f kubeclaw-values.yaml

Using an existing secret

If you manage secrets externally (Sealed Secrets, External Secrets, etc.), set secret.create=false and point to your secret:

secret:
  create: false
  existingSecretName: my-kubeclaw-secret

The referenced Secret must contain OPENCLAW_GATEWAY_TOKEN and any provider API keys.

After install

1. Wait for the StatefulSet:

   shell

   $

   kubectl -n kubeclaw rollout status statefulset/kubeclaw
   

2. Generate an authenticated dashboard URL:

   shell

   $

   kubectl -n kubeclaw exec statefulset/kubeclaw -- \
     node dist/index.js dashboard --no-open | grep "Dashboard URL:"
   

3. Port-forward to access the Control UI:

   shell

   $

   kubectl -n kubeclaw port-forward svc/kubeclaw 18789:18789
   

Upgrade

helm upgrade kubeclaw oci://ghcr.io/imerica/kubeclaw \
  --namespace kubeclaw \
  --version <new-version> \
  -f kubeclaw-values.yaml

Each chart release pins image.tag and image.digest to the validated candidate image. Upgrading the chart version upgrades the Gateway image deterministically.

Uninstall

helm uninstall kubeclaw --namespace kubeclaw

This removes the release but preserves PVCs. Delete them manually if you want a clean slate:

kubectl -n kubeclaw delete pvc -l app.kubernetes.io/name=kubeclaw

Verify

Validate rendered manifests before applying:

helm lint oci://ghcr.io/imerica/kubeclaw -f kubeclaw-values.yaml

Render templates without installing and pipe to kubeconform:

helm template kubeclaw oci://ghcr.io/imerica/kubeclaw \
  -f kubeclaw-values.yaml | kubeconform -strict

The chart's CI runs helm-lint, kubeconform, kube-linter, and Trivy scans on every commit.

Troubleshooting

Pod not starting. Check events and logs:

kubectl -n kubeclaw describe pod -l app.kubernetes.io/name=kubeclaw

kubectl -n kubeclaw logs statefulset/kubeclaw

Common causes: missing OPENCLAW_GATEWAY_TOKEN, missing provider API keys, or insufficient PVC capacity.

Dashboard URL not working. You must run the dashboard command from inside the Gateway pod to get a valid authenticated URL. Port-forwarding alone is not enough.

LiteLLM not starting. Ensure litellm.masterkey is set and starts with sk-. Check the LiteLLM pod logs separately:

kubectl -n kubeclaw logs -l app.kubernetes.io/name=kubeclaw-litellm

Tailscale not connecting. Verify your auth key is valid and not expired. Check the Tailscale sidecar logs:

kubectl -n kubeclaw logs statefulset/kubeclaw -c tailscale

Egress filter blocking legitimate traffic. Review Blocky query logs and adjust egressFilter.allowlists or egressFilter.customConfig. See the Configuration reference.

JavaScript heap out of memory. Increase nodeOptions (default: --max-old-space-size=768). Keep the value below your container memory limit to leave room for native allocations.

For backup and recovery, see the Restore Runbook.