Skip to main content
Installing Flokoa places two components on your cluster: the controller-manager (the operator that watches your CRDs and reconciles agent state) and a full set of Custom Resource Definitions that let you manage agents, models, providers, and tools declaratively. The operator runs in a dedicated flokoa-system namespace and requires no changes to your existing workloads.

​
Prerequisites

Before you install Flokoa, make sure your environment meets the following requirements:
  • Kubernetes 1.25 or later — any conformant distribution (EKS, GKE, AKS, k3s, kind, etc.)
  • kubectl configured to access your target cluster (kubectl cluster-info should return successfully)
  • Helm 3.x (optional) — required only if you prefer the Helm-based install path
  • Argo Workflows (optional) — required only if you plan to use the AgentWorkflow resource for multi-agent pipelines
The flokoa-system namespace is created automatically by both the bundle and the Helm chart. You do not need to create it in advance.

​
Quick install (single YAML bundle)

The fastest way to get Flokoa running is to apply the pre-built install bundle from the latest GitHub release. This single manifest installs the CRDs, RBAC resources, and the operator Deployment in one step.
1

Apply the install bundle

Run the following command against your cluster. kubectl will create all required namespaces, CRDs, and the operator pod.
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
2

Verify the operator is running

Wait a few seconds for the pod to start, then confirm it is in the Running state:
kubectl get pods -n flokoa-system
You should see output similar to:
NAME                                           READY   STATUS    RESTARTS   AGE
flokoa-controller-manager-6d8f9b7c4f-xk9p2   1/1     Running   0          30s
3

Verify CRDs are registered

Confirm that all six Custom Resource Definitions are available in your cluster:
kubectl get crds | grep flokoa
Expected output:
agenttools.agent.flokoa.ai
agentworkflows.agent.flokoa.ai
agents.agent.flokoa.ai
instructions.agent.flokoa.ai
modelproviders.agent.flokoa.ai
models.agent.flokoa.ai

​
Helm install

If you manage your cluster infrastructure with Helm, install Flokoa from the OCI registry. This approach gives you full control over values such as replica counts, resource limits, metrics endpoints, and Argo Workflows integration.
1

Install the Flokoa Helm chart

Pull and install the chart from the OCI registry in a single command. Pass --create-namespace so Helm creates flokoa-system if it does not already exist.
helm install flokoa oci://ghcr.io/danielnyari/charts/flokoa \
  --namespace flokoa-system \
  --create-namespace
To customise the installation, pass --set flags or supply a values file:
helm install flokoa oci://ghcr.io/danielnyari/charts/flokoa \
  --namespace flokoa-system \
  --create-namespace \
  --set controller.replicas=2 \
  --set controller.metrics.serviceMonitor.enabled=true
2

Verify the installation

Confirm the operator pod and (if enabled) the server pod are running:
kubectl get pods -n flokoa-system
A successful install shows both pods in Running status:
NAME                                           READY   STATUS    RESTARTS   AGE
flokoa-controller-manager-6d8f9b7c4f-xk9p2   1/1     Running   0          45s
flokoa-server-7b9c84d5f-lmr3w                1/1     Running   0          45s
To enable Argo Workflows support at install time, add --set argo.enabled=true to your Helm command. Argo Workflows must already be installed in your cluster before enabling this flag.

​
Upgrading

Keep Flokoa up to date by re-applying the latest bundle or running a Helm upgrade. Both methods perform a rolling update of the operator without downtime for your running agents. 
# Re-apply the latest bundle
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml

# Or with Helm
helm upgrade flokoa oci://ghcr.io/danielnyari/charts/flokoa -n flokoa-system

​
Uninstalling

Delete all Flokoa resources (Agents, Models, ModelProviders, AgentTools) before removing the operator. Removing the operator while resources still exist can leave orphaned Deployments and Services in your cluster because the finalizer logic will no longer run.
Remove all agent resources first, then delete the operator: 
# Remove all agents across every namespace
kubectl delete agents --all --all-namespaces

# Remove other Flokoa resources
kubectl delete agenttools --all --all-namespaces
kubectl delete models --all --all-namespaces
kubectl delete modelproviders --all --all-namespaces

# Remove the operator (bundle install)
kubectl delete -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml

# Or with Helm
helm uninstall flokoa -n flokoa-system