> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Started with Flokoa: Deploy Your First AI Agent
> Install the Flokoa operator, connect an OpenAI model provider, and deploy your first AI agent on Kubernetes in under five minutes.
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.
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:
```bash theme={null}
kubectl version --short
kubectl cluster-info
```
Apply the single-file install manifest. This creates the `flokoa-system` namespace, installs all six Custom Resource Definitions, and deploys the operator controller.
```bash theme={null}
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
```
Wait for the operator pod to become ready:
```bash theme={null}
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.
Store your OpenAI API key as a Kubernetes Secret in the namespace where you'll deploy your agent:
```bash theme={null}
kubectl create secret generic openai-credentials \
--from-literal=api-key=sk-proj-...
```
Now declare a `ModelProvider` that references that secret:
```yaml theme={null}
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:
```bash theme={null}
kubectl apply -f modelprovider.yaml
```
A `Model` resource selects a specific model name and inference parameters, wiring them to your `ModelProvider`. Create a `model.yaml` file:
```yaml theme={null}
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:
```bash theme={null}
kubectl apply -f model.yaml
```
Verify both resources are ready:
```bash theme={null}
kubectl get modelproviders
kubectl get models
```
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.
```yaml theme={null}
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:
```bash theme={null}
kubectl apply -f agent.yaml
```
Replace `ghcr.io/example/simple-agent:latest` with your own agent image. See the [Agent resource reference](/resources/agent) for the full spec including environment variables, resource limits, and health check configuration.
Watch the agent come up and confirm it reaches the `Running` phase:
```bash theme={null}
kubectl get agents
```
Expected output:
```
NAME PHASE AGE
my-first-agent Running 45s
```
For detailed information including status conditions, events, and the resolved model:
```bash theme={null}
kubectl describe agent my-first-agent
```
If the agent is stuck in `Pending`, check the underlying pod events:
```bash theme={null}
kubectl get pods -l flokoa.ai/agent=my-first-agent
kubectl describe pod
```
To stream logs from the running agent:
```bash theme={null}
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.
Learn the full Agent spec: replica counts, resource limits, health checks, tool bindings, and more.
Configure Anthropic, Google Gemini, or AWS Bedrock as an alternative to OpenAI.
Use the Flokoa Python SDK and CLI to build agents, call them programmatically, and integrate with pydantic-ai or Google ADK.