> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Flokoa on your Kubernetes cluster

> Install the Flokoa operator and CRDs on any Kubernetes 1.25+ cluster using a single YAML bundle or the OCI Helm chart.

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

<Note>
  The `flokoa-system` namespace is created automatically by both the bundle and the Helm chart. You do not need to create it in advance.
</Note>

***

## 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.

<Steps>
  <Step title="Apply the install bundle">
    Run the following command against your cluster. kubectl will create all required namespaces, CRDs, and the operator pod.

    ```bash theme={null}
    kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
    ```
  </Step>

  <Step title="Verify the operator is running">
    Wait a few seconds for the pod to start, then confirm it is in the `Running` state:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Verify CRDs are registered">
    Confirm that all six Custom Resource Definitions are available in your cluster:

    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

***

## 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.

<Steps>
  <Step title="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.

    ```bash theme={null}
    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:

    ```bash theme={null}
    helm install flokoa oci://ghcr.io/danielnyari/charts/flokoa \
      --namespace flokoa-system \
      --create-namespace \
      --set controller.replicas=2 \
      --set controller.metrics.serviceMonitor.enabled=true
    ```
  </Step>

  <Step title="Verify the installation">
    Confirm the operator pod and (if enabled) the server pod are running:

    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

<Tip>
  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.
</Tip>

***

## 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.

```bash theme={null}
# 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

<Warning>
  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.
</Warning>

Remove all agent resources first, then delete the operator:

```bash theme={null}
# 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
```