Récif
Récifdocs

v0.1.0 · Apache 2.0

Search docs...

Quickstart

From zero to a running AI agent in 10 minutes.

5 min read

Prerequisites

  • Kubernetes cluster (v1.28+) — Colima (Mac), Kind (Linux), or any cloud K8s
  • Helm (v3.12+)
  • kubectl configured for your cluster
# Mac — quickest local setup
colima start --kubernetes --cpu 4 --memory 8

Step 1: Install Récif

helm install recif oci://ghcr.io/recif-platform/helm-charts/recif:0.1.0 \
  --namespace recif-system --create-namespace

Tip

This installs the API, Operator, Dashboard, and PostgreSQL. No LLM is included — you bring your own (see Step 2).

Verify everything is running:

kubectl get pods -n recif-system

You should see: recif-api, recif-operator, recif-dashboard, recif-postgresql — all Running.

Step 2: Choose Your LLM Provider

Pick the provider you want to use. Each one requires different credentials.

OpenAI

Best for: getting started fast, strong reasoning, tool use.

# Create a secret with your API key
kubectl create namespace team-default
kubectl create secret generic openai-credentials \
  --namespace team-default \
  --from-literal=OPENAI_API_KEY=sk-proj-your-key-here

Your agent config will use:

modelType: openai
modelId: gpt-4o-mini          # or gpt-4o, o3-mini
envSecrets: [openai-credentials]

Get your key → platform.openai.com/api-keys

Anthropic

Best for: long context, careful reasoning, native tool use.

kubectl create namespace team-default
kubectl create secret generic anthropic-credentials \
  --namespace team-default \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-your-key-here

Your agent config will use:

modelType: anthropic
modelId: claude-sonnet-4-20250514    # or claude-haiku
envSecrets: [anthropic-credentials]

Get your key → console.anthropic.com/settings/keys

Google AI (Gemini)

Best for: free tier, fast, multimodal.

kubectl create namespace team-default
kubectl create secret generic google-ai-credentials \
  --namespace team-default \
  --from-literal=GOOGLE_API_KEY=AIza-your-key-here

Your agent config will use:

modelType: google-ai
modelId: gemini-2.5-flash      # or gemini-2.5-pro
envSecrets: [google-ai-credentials]

Get your key → aistudio.google.com/apikey (free tier available)

Ollama (Local)

Best for: offline, free, data privacy. Requires Ollama installed on your machine.

# On your machine (not in K8s)
ollama pull qwen3.5:4b
ollama serve    # runs on port 11434
# Tell the agent where to find Ollama (on your host machine)
kubectl create namespace team-default
kubectl create secret generic ollama-config \
  --namespace team-default \
  --from-literal=OLLAMA_BASE_URL=http://host.docker.internal:11434

Your agent config will use:

modelType: ollama
modelId: qwen3.5:4b
envSecrets: [ollama-config]

Note

host.docker.internalresolves to your Mac from inside K8s (Colima/Docker Desktop). On Linux, use your machine's IP instead.

Vertex AI (Google Cloud)

Best for: production, enterprise, GCP-native, billing controls.

# Create a GCP service account and download the key
gcloud iam service-accounts keys create sa-key.json \
  --iam-account=my-agent@my-project.iam.gserviceaccount.com
 
kubectl create namespace team-default
kubectl create secret generic my-agent-gcp-sa \
  --namespace team-default \
  --from-file=credentials.json=sa-key.json

Your agent config will use:

modelType: vertex-ai
modelId: gemini-2.5-flash
gcpServiceAccount: "my-agent@my-project.iam.gserviceaccount.com"

See LLM Providers Guide for full Vertex AI setup.

AWS Bedrock

Best for: AWS-native, enterprise, existing AWS infrastructure.

kubectl create namespace team-default
kubectl create secret generic bedrock-credentials \
  --namespace team-default \
  --from-literal=AWS_ACCESS_KEY_ID=AKIA-your-key \
  --from-literal=AWS_SECRET_ACCESS_KEY=your-secret \
  --from-literal=AWS_REGION=us-east-1

Your agent config will use:

modelType: bedrock
modelId: anthropic.claude-sonnet-4-20250514-v1:0
envSecrets: [bedrock-credentials]

Step 3: Create Your First Agent

Replace modelType, modelId, and envSecrets with your choice from Step 2.

# agent.yaml
apiVersion: agents.recif.dev/v1
kind: Agent
metadata:
  name: my-first-agent
  namespace: team-default
spec:
  name: "My First Agent"
  framework: corail
  strategy: agent-react
  channel: rest
  modelType: openai                    # ← your provider
  modelId: gpt-4o-mini                # ← your model
  envSecrets:
    - openai-credentials              # ← your secret name
  image: ghcr.io/recif-platform/corail:v0.1.0
  replicas: 1
kubectl apply -f agent.yaml

Wait for the agent to be ready:

kubectl get pods -n team-default -w
# Wait until STATUS = Running, READY = 1/1

Step 4: Chat with Your Agent

# Port-forward the API
kubectl port-forward -n recif-system svc/recif-api 8080:8080 &
 
# Send a message
curl -N http://localhost:8080/api/v1/agents/my-first-agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello! What can you do?"}'

You'll see SSE events streaming back with the agent's response.

Step 5: Open the Dashboard

kubectl port-forward -n recif-system svc/recif-dashboard 3000:3000 &

Open http://localhost:3000 — you'll see your agent in the dashboard, ready to chat.

Optional: Canary Deployments

To enable canary deployments (champion/challenger with traffic splitting), install Istio + Kiali:

# Requires: istioctl (brew install istioctl)
./scripts/setup-istio.sh

This installs Istio (service mesh), Prometheus (metrics), and Kiali (mesh dashboard). After install:

  • Agent pods get an Istio sidecar automatically (2/2 containers)
  • You can deploy a challenger version alongside the champion
  • Flagger webhook queries MLflow eval scores to auto-promote or auto-rollback
  • Kiali shows the mesh traffic in real-time
# Kiali dashboard
kubectl port-forward -n istio-system svc/kiali 20001:20001 &
# Open http://localhost:20001

Note

Istio adds ~500MB of images and 3 extra pods. Skip this step if you don't need canary deployments yet.

See Canary Deployments Guide for the full workflow.

Alternative: Create Agent via API

The quickstart above uses kubectl apply (CRD). You can also create agents via the Récif API, which registers the agent in the database and enables the full lifecycle (releases, evaluation, governance).

# Create agent
curl -X POST http://localhost:8080/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Agent",
    "description": "Created via API",
    "framework": "corail",
    "version": "0.1.0",
    "model_type": "ollama",
    "model_id": "qwen3.5:4b"
  }'
 
# Deploy (replace AGENT_ID with the id from the response)
curl -X POST http://localhost:8080/api/v1/agents/AGENT_ID/deploy

The API flow gives you:

  • Agent in the Récif database (visible in dashboard)
  • Evaluation and release pipeline
  • Feedback loop (thumbs up/down)
  • Governance scorecards

Tip

Use the API for production workflows. Usekubectlapplyfor quick testing.

What's Next?

  • Create an Agent — full CRD reference and API options
  • LLM Providers — detailed setup for each provider with security best practices
  • Evaluation — set up eval-gated releases with MLflow scorers
  • Architecture — understand how the pieces fit together