Skip to content

Installation

This page walks you through installing Purko on a Kubernetes cluster, from prerequisites to a running operator with the CLI tool purkoctl.

Prerequisites

Tool Version Purpose
kubectl >= 1.26 Cluster interaction
Kubernetes >= 1.26 Target cluster
Helm >= 3 Install the Purko chart
Go >= 1.21 Build purkoctl (optional if you use pre-built binaries)

For local development, minikube is the recommended cluster. The Purko operator works best with at least 4 CPUs and 8 GB of RAM allocated.

Minikube quick start

Start a local cluster with enough resources:

minikube start --driver=podman --cpus=4 --memory=8192

If you use the podman driver, you will also need to enable hostNetwork for the operator (covered below).

Step 1 — Install the CRDs

The CRDs are installed separately from the chart so their lifecycle is explicit (Helm does not upgrade CRDs on helm upgrade):

kubectl apply -k "https://github.com/purko-io/purko/crds?ref=main"

Or, from a clone: kubectl apply -f crds/.

Step 2 — Install the Helm chart

Option A — OCI registry (no clone needed):

helm install purko oci://ghcr.io/purko-io/purko \
  --namespace purko-system --create-namespace

The OCI chart bundles the CRDs from v0.2.1 onward (Helm installs a chart's crds/ on first install, but never upgrades them — Step 1 remains the way to upgrade CRDs).

Option B — from source:

git clone https://github.com/purko-io/purko.git
cd purko
helm install purko deploy/helm/ --create-namespace --namespace purko-system

The chart installs:

  • The Purko operator Deployment in purko-system
  • RBAC (ServiceAccount, ClusterRole, ClusterRoleBinding)
  • A dashboard Service on port 8082
  • The starter agent library and the ai-agents namespace for your Agent and Workflow resources
  • The execution history PVC (operator.history.enabled)

Key values

The chart is configured through deploy/helm/values.yaml. The most commonly changed values:

Value Default Description
llm.provider "" (auto-detect) LLM provider: anthropic, openai, vertex-ai, ollama
llm.model claude-sonnet-4-6 Default model name
operator.hostNetwork false Set true for minikube/podman
dashboard.port 8082 Dashboard and API port
webhooks.enabled false Enable server-side webhook validation

Override values at install time:

helm install purko deploy/helm/ \
  --namespace purko-system \
  --create-namespace \
  --set llm.provider=anthropic \
  --set llm.credentials.secretName=anthropic-api-key

minikube / podman networking

Pod-to-pod networking does not work correctly with the podman driver by default. Enable hostNetwork so the operator and MCP servers bind to the host network:

helm install purko deploy/helm/ \
  --namespace purko-system \
  --create-namespace \
  --set operator.hostNetwork=true

When hostNetwork: true is set, MCP servers are also registered as localhost:<port> instead of their ClusterIP address.

Step 3 — Verify the operator is running

kubectl get pods -n purko-system

Expected output:

NAME                               READY   STATUS    RESTARTS   AGE
purko-operator-xxxxx-yyyyy         1/1     Running   0          30s

Check that the CRDs were installed:

kubectl get crds | grep purko

Expected output:

agents.purko.io                     2026-04-23T09:00:00Z
agentautonomypolicies.purko.io      2026-04-23T09:00:00Z
llmproviders.purko.io               2026-04-23T09:00:00Z
mcpservers.purko.io                 2026-04-23T09:00:00Z
workflows.purko.io                  2026-04-23T09:00:00Z

Check that the API resources are registered (note the short names):

kubectl api-resources | grep purko

agents                ag    purko.io/v1alpha1    true    Agent
workflows             wf    purko.io/v1alpha1    true    Workflow
mcpservers            mcp   purko.io/v1alpha1    true    MCPServer
llmproviders          llm   purko.io/v1alpha1    true    LLMProvider

The short names (ag, wf, mcp, llm) can be used anywhere you would type the full resource name.

The chart also installs the starter agent library — six archetype agents (task-router, project-planner, code-executor, code-reviewer, system-monitor, knowledge-retriever) so the dashboard has a working agent set immediately:

kubectl get agents -n ai-agents

Their model provider/name come from starterAgents.provider and starterAgents.model in the Helm values (the provider name resolves against your LLMProvider resources, falling back to the one marked default: true). Set starterAgents.enabled: false if you manage agents yourself.

Step 3 — Access the Dashboard (Pro)

The Purko dashboard is available in Purko Pro. It provides a UI for creating agents, monitoring workflows, and browsing MCP tool catalogs. Community edition users manage everything via purkoctl CLI and kubectl.

kubectl port-forward -n purko-system deploy/purko-operator 8082:8082

Then open http://localhost:8082 in your browser.

Tip

Keep the port-forward running in a separate terminal while you follow the rest of the Getting Started guide.

The dashboard also exposes a REST API at http://localhost:8082/api/. The CLI (purkoctl) uses this API internally.

Step 5 — Install purkoctl

purkoctl is a CLI for managing agents, workflows, and MCP servers from the terminal. Build it from source:

# From the repository root
go build \
  -ldflags "-X main.version=$(git describe --tags --always)" \
  -o bin/purkoctl \
  ./cmd/purkoctl/

Move the binary to a directory on your PATH:

mv bin/purkoctl /usr/local/bin/purkoctl

Verify the installation:

purkoctl version

Expected output:

purkoctl v0.1.0-alpha (build: abc1234)
API: http://localhost:8082

Tip

purkoctl defaults to http://localhost:8082 as the API endpoint. If you change the dashboard port or run it on a remote cluster, set the PURKO_API environment variable:

export PURKO_API=http://my-cluster:8082

Uninstall

Remove all agent and workflow resources before uninstalling, or their finalizers will block deletion:

kubectl delete agents,workflows --all -A
helm uninstall purko --namespace purko-system
kubectl delete namespace purko-system

To remove the CRDs as well (this deletes all stored Agent and Workflow data):

kubectl get crds | grep purko | awk '{print $1}' | xargs kubectl delete crd

Next steps