Skip to main content
This guide walks you through everything you need to deploy your first AI agent with Flokoa — from installing the operator to confirming your agent is running. By the end, you’ll have a working Agent resource in your cluster backed by an OpenAI model.
1

Check the prerequisites

Before you begin, make sure you have the following in place:
  • Kubernetes 1.25 or later — any conformant cluster works (local clusters like kind or minikube are fine for development)
  • kubectl configured to communicate with your target cluster
  • An OpenAI API key — you’ll store this in a Kubernetes Secret
You can verify your cluster version and connectivity with:
kubectl version --short
kubectl cluster-info
2

Install the Flokoa operator

Apply the single-file install manifest. This creates the flokoa-system namespace, installs all six Custom Resource Definitions, and deploys the operator controller.
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
Wait for the operator pod to become ready:
kubectl get pods -n flokoa-system
You should see output similar to:
NAME                                READY   STATUS    RESTARTS   AGE
flokoa-controller-manager-xyz-abc   2/2     Running   0          30s
The operator runs in the flokoa-system namespace and manages resources across all namespaces in your cluster. It requires cluster-scoped permissions to watch and manage CRDs, Deployments, and Services.
3

Create an OpenAI secret and ModelProvider

Store your OpenAI API key as a Kubernetes Secret in the namespace where you’ll deploy your agent:
kubectl create secret generic openai-credentials \
  --from-literal=api-key=sk-proj-...
Now declare a ModelProvider that references that secret:
apiVersion: agent.flokoa.ai/v1alpha1
kind: ModelProvider
metadata:
  name: openai-provider
  labels:
    provider: openai
spec:
  apiKeySecretRef:
    name: openai-credentials
    key: api-key
  openai:
    timeoutSeconds: 60
Save this as modelprovider.yaml and apply it:
kubectl apply -f modelprovider.yaml
4

Create a Model resource

A Model resource selects a specific model name and inference parameters, wiring them to your ModelProvider. Create a model.yaml file:
apiVersion: agent.flokoa.ai/v1alpha1
kind: Model
metadata:
  name: gpt-4o
  labels:
    provider: openai
    model: gpt-4o
spec:
  model: "gpt-4o"
  providerRef:
    name: openai-provider
  parameters:
    temperature: "0.7"
    maxTokens: 8192
    topP: "0.9"
Apply it:
kubectl apply -f model.yaml
Verify both resources are ready:
kubectl get modelproviders
kubectl get models
5

Deploy your first agent

Now create your first Agent resource. This minimal example uses the standard runtime mode — you supply the container image and the operator handles the Deployment and Service.
apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: my-first-agent
spec:
  model:
    name: gpt-4o
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/simple-agent:latest
        ports:
        - containerPort: 8080
          name: http
Save this as agent.yaml and apply it:
kubectl apply -f agent.yaml
Replace ghcr.io/example/simple-agent:latest with your own agent image. See the Agent resource reference for the full spec including environment variables, resource limits, and health check configuration.
6

Check your agent's status

Watch the agent come up and confirm it reaches the Running phase:
kubectl get agents
Expected output:
NAME             PHASE     AGE
my-first-agent   Running   45s
For detailed information including status conditions, events, and the resolved model:
kubectl describe agent my-first-agent
If the agent is stuck in Pending, check the underlying pod events:
kubectl get pods -l flokoa.ai/agent=my-first-agent
kubectl describe pod <pod-name>
To stream logs from the running agent:
kubectl logs -l flokoa.ai/agent=my-first-agent -f
If the Agent phase shows Failed, run kubectl describe agent my-first-agent and look at the Status.Conditions section. Common causes include an inaccessible container image, a missing Secret, or a ModelProvider that hasn’t resolved yet.

​
What’s next?

You have a running agent — here are the natural next steps depending on what you want to explore.

Agent resource reference

Learn the full Agent spec: replica counts, resource limits, health checks, tool bindings, and more.

Connect an LLM provider

Configure Anthropic, Google Gemini, or AWS Bedrock as an alternative to OpenAI.

SDK overview

Use the Flokoa Python SDK and CLI to build agents, call them programmatically, and integrate with pydantic-ai or Google ADK.