Install NimbleTools Runtime on your Kubernetes cluster in minutes using our automated installer or manual Helm setup.
Prerequisites Before installing NimbleTools Runtime, ensure you have:
Kubernetes Cluster k3d, minikube, or any Kubernetes 1.24+
Helm 3.0+ Package manager for Kubernetes
kubectl Kubernetes command-line tool
ntcli (optional) NimbleTools CLI for easier management
Quick Installation The fastest way to get started is using our automated installer script:
curl -sSL https://raw.githubusercontent.com/NimbleBrainInc/nimbletools-core/refs/heads/main/install.sh | bash
This script will:
Check for required dependencies (helm, k3d, kubectl)
Create a local k3d cluster (if needed)
Install the NimbleTools operator
Deploy the REST API
Configure the service registry
The entire installation process takes approximately 2-3 minutes.
Manual Installation (Advanced) For production deployments or custom configurations, install directly from the OCI registry.
Step 1: Create Kubernetes Cluster (Local) If you don’t have a Kubernetes cluster, create one locally with k3d:
# Install k3d curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash # Create cluster with ingress ports k3d cluster create nimbletools-quickstart \ --port "80:80@loadbalancer" \ --port "443:443@loadbalancer" \ --k3s-arg "--disable=traefik@server:0" # Verify cluster kubectl cluster-info
NimbleTools uses an OCI-based Helm chart hosted on GitHub Container Registry:
# Install the complete platform (operator + control plane + RBAC) helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set global.domain=nimbletools.dev \ --set ingress.enabled= true \ --wait
The unified nimbletools-core chart includes the MCP operator, control plane API, and RBAC controller.
Step 3: Verify Installation # Check all pods are running kubectl get pods -n nimbletools-system # Check CRD is installed kubectl get crd mcpservices.mcp.nimbletools.dev # Check services kubectl get svc -n nimbletools-system
Expected output:
NAME READY STATUS RESTARTS AGE nimbletools-core-operator-xxx 1/1 Running 0 2m nimbletools-core-control-plane-xxx 1/1 Running 0 2m nimbletools-core-rbac-controller-xxx 1/1 Running 0 2m
Add these entries to /etc/hosts for local access:
127.0.0.1 api.nimbletools.dev 127.0.0.1 mcp.nimbletools.dev
Then verify the endpoints:
curl http://api.nimbletools.dev/health curl http://mcp.nimbletools.dev/health
Production Installation For production environments, consider these additional configurations:
High Availability Deploy with multiple replicas and resource limits:
helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set operator.replicaCount= 3 \ --set controlPlane.replicaCount= 3 \ --set operator.resources.requests.memory="512Mi" \ --set operator.resources.requests.cpu="500m" \ --wait
TLS/SSL Configuration Enable TLS for secure communications:
helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set global.domain=nimbletools.example.com \ --set ingress.enabled= true \ --set ingress.tls.enabled= true \ --set ingress.className=nginx \ --set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt-prod \ --wait
Custom Values File Create a values.yaml for complex configurations:
# values.yaml global : domain : nimbletools.example.com operator : replicaCount : 3 image : tag : "0.4.0" pullPolicy : IfNotPresent resources : requests : memory : "512Mi" cpu : "500m" limits : memory : "1Gi" cpu : "1000m" controlPlane : replicaCount : 3 resources : requests : memory : "512Mi" cpu : "500m" ingress : enabled : true className : nginx annotations : cert-manager.io/cluster-issuer : letsencrypt-prod tls : enabled : true monitoring : enabled : true
Install with custom values:
helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ -f values.yaml \ --wait
Cloud Provider Installation AWS EKS
GCP GKE
Azure AKS
# Create EKS cluster eksctl create cluster \ --name nimbletools \ --region us-west-2 \ --nodegroup-name standard-workers \ --node-type t3.medium \ --nodes 3 # Install NimbleTools helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set global.domain=nimbletools.example.com \ --set ingress.enabled= true \ --wait
# Create GKE cluster gcloud container clusters create nimbletools \ --zone us-central1-a \ --num-nodes 3 \ --machine-type n1-standard-2 # Install NimbleTools helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set global.domain=nimbletools.example.com \ --set ingress.enabled= true \ --wait
# Create AKS cluster az aks create \ --resource-group nimbletools-rg \ --name nimbletools \ --node-count 3 \ --node-vm-size Standard_DS2_v2 # Get credentials az aks get-credentials \ --resource-group nimbletools-rg \ --name nimbletools # Install NimbleTools helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --set global.domain=nimbletools.example.com \ --set ingress.enabled= true \ --wait
Installing ntcli The NimbleTools CLI simplifies interaction with the runtime:
# macOS/Linux curl -sSL https://install.nimbletools.ai/cli | bash # Or with npm npm install -g @nimbletools/ntcli # Verify installation ntcli version
Configure ntcli to use your runtime:
# Point to local runtime ntcli config set endpoint http://localhost:8080 # Or production runtime ntcli config set endpoint https://api.nimbletools.example.com # Verify connection ntcli health
Troubleshooting
Pods stuck in Pending state
Cause : Insufficient cluster resourcesSolution :# Check node resources kubectl describe nodes # Increase cluster size (k3d) k3d cluster delete nimbletools k3d cluster create nimbletools --agents 5
Cause : Operator not installed correctlySolution :# Reinstall the platform helm uninstall nimbletools-core -n nimbletools-system helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --create-namespace \ --wait # Verify CRDs kubectl get crd | grep nimbletools
Cause : Ingress not configured or port not forwardedSolution :# Port forward API service kubectl port-forward -n nimbletools-system \ svc/nimbletools-api 8080:80 # Access at http://localhost:8080
Cause : RBAC not configured correctlySolution :# Check service account kubectl get serviceaccount -n nimbletools-system # Check role bindings kubectl get rolebinding,clusterrolebinding -n nimbletools-system # Reinstall with proper RBAC helm upgrade --install nimbletools-core \ oci://ghcr.io/nimblebraininc/charts/nimbletools-core \ --namespace nimbletools-system \ --set rbacController.enabled= true \ --wait
Next Steps 
