Purple Flea brings per-pod financial accountability to Kubernetes agent workloads. Store
credentials in K8s Secrets, inject them into Jobs via env vars, claim free USDC in
initContainers, auto-release escrow on Job completion via a Python operator, run payroll
as a CronJob, and scale pods based on escrow queue depth.
1%
Escrow fee
15%
Referral on fees
$1
Free faucet credit
REST + MCP
API access
First-time cluster? Run the initContainer pattern below on your first Job —
it automatically registers the pod as a new agent and claims $1 free USDC from
faucet.purpleflea.com
before your main container starts. Zero-cost first run, every time.
Credentials
Store Purple Flea credentials in a K8s Secret
Never put API keys in Pod specs directly. Kubernetes Secrets are base64-encoded at rest
(and encrypted if you configure KMS) and can be mounted as environment variables or files
without appearing in YAML committed to your repo.
1
Create the Secret with kubectl
Pass credentials as literal strings. Kubernetes handles base64 encoding automatically.
kubectl create secret generic purpleflea-creds \
--namespace=agent-jobs \
--from-literal=api-key=pf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
--from-literal=agent-wallet=agent-k8s-prod-cluster-001 \
--from-literal=faucet-url=https://faucet.purpleflea.com \
--from-literal=escrow-url=https://escrow.purpleflea.com
# Verify it was created
kubectl get secret purpleflea-creds -n agent-jobs -o yaml
2
RBAC: restrict who can read the Secret
Create a ServiceAccount and Role that only the agent Job pods can read the Secret. Other pods in the namespace cannot.
# rbac.yaml
Encryption at rest: For production clusters, enable
EncryptionConfiguration
with a KMS provider (AWS KMS, GCP CKMS, Azure Key Vault). This encrypts Secret values in
etcd so that even etcd backups don't expose your PF_API_KEY.
Job Spec
Job spec with faucet claim in initContainer
The initContainer pattern claims free USDC from the Purple Flea faucet the first time a new
agent pod runs. The init container registers the agent and claims $1, then writes the result
to an emptyDir volume shared with the main container. The main container reads the claimed
balance and uses it to fund its first escrow.
# agent-job.yaml
One claim per agent ID: The faucet allows exactly one $1 USDC claim per
agent_id. The initContainer above handles the
409 Already Claimed response gracefully and continues.
Use a unique agent_id per logical agent, not per Job run.
Operator Pattern
Python operator: auto-release escrow on Job completion
A Kubernetes operator is a controller that watches API objects and acts on state changes.
This lightweight Python operator watches for Job completion events and automatically
releases the associated Purple Flea escrow — removing the need for agent code to manage
payment lifecycle explicitly.
👁️
Watch Job events
The operator uses the Kubernetes Python client to stream Job events. When a Job reaches Complete or Failed status, it triggers payment action.
🔒
Escrow ID from annotation
Jobs annotate themselves with the escrow ID at creation time: purpleflea.com/escrow-id. The operator reads this annotation to know which escrow to release.
✅
Release on success
Job succeeded — operator calls POST /api/escrow/{"{id}"}/release. Payee receives funds minus 1% fee.
🚫
Dispute on failure
Job failed after all retries — operator raises a dispute. Funds are frozen pending human review. No automatic refund without review.
# operator/main.py — deploy as a Deployment in the cluster
# operator-deployment.yaml
Annotate each Job with its escrow ID so the operator can find it. The Job creation flow is:
call Purple Flea Escrow to get an escrow ID, then use that ID in the Job annotation before
submitting with kubectl apply.
# Annotate a Job with its escrow ID before submitting
CronJob Pattern
CronJob periodic payroll to agent pods
For long-running agent deployments (Deployments, StatefulSets) rather than batch Jobs,
use a CronJob to run periodic payroll. The payroll pod queries each agent pod's work log,
tallies tasks completed since the last run, and releases escrows in bulk.
# payroll-cronjob.yaml — runs at the top of every hour
Referral income from payroll: If your payroll agent was registered using a
referrer code, 15% of every escrow fee your agents pay goes back to the referrer. At scale,
running 100 agent pods paying $0.10/task at 1% fee = $0.10/task in fees, 15% of which
($0.015/task) returns to the referrer automatically.
Helm Integration
Helm values snippet for Purple Flea integration
If you manage your agent deployment with Helm, add Purple Flea configuration to your
values.yaml. The chart templates below read these values
to inject credentials and configure the MCP sidecar.
# values.yaml (partial)
# templates/deployment.yaml (excerpt) — inject from values
MCP Sidecar
MCP sidecar container in Pod spec
Run a Purple Flea MCP proxy sidecar alongside your agent container. The sidecar connects
to faucet.purpleflea.com/mcp and
escrow.purpleflea.com/mcp and exposes them on localhost
inside the pod. Your agent calls http://localhost:8765 —
no external TLS overhead on every tool call.
# pod-with-mcp-sidecar.yaml
Why a sidecar instead of direct calls? The sidecar lets you:
(1) cache MCP tool schemas so each agent call doesn't re-fetch them,
(2) add retry logic and circuit-breaking transparently,
(3) log all MCP traffic to a central observability stack without modifying agent code,
and (4) rotate credentials by restarting only the sidecar, not the agent.
Auto-scaling
HPA trigger: scale pods when escrow queue depth exceeds threshold
Use a custom Horizontal Pod Autoscaler metric sourced from the Purple Flea escrow queue.
When pending escrows (tasks waiting to be processed) exceed a threshold, Kubernetes
automatically adds more agent pods. When the queue drains, pods scale back down.
This creates an economically-driven autoscaler — more demand, more capacity, more revenue.
📊
Custom metric server
A small service polls GET /api/escrows?status=pending and exposes the count as a Kubernetes custom metric: escrow_queue_depth.
⚡
Demand-driven scaling
When queue depth > 10, the HPA scales agent replicas up (max 20). When queue drains below 2, it scales down (min 2). No manual intervention.
# metrics-server/main.py — expose escrow queue depth as a K8s custom metric
# hpa.yaml — Horizontal Pod Autoscaler using escrow queue depth
Budget cap: With maxReplicas: 20 and a
task budget of $0.10 per pod, your maximum hourly escrow exposure is
$0.10 x 20 = $2.00/hour plus 1% fees ($0.02). Set
maxReplicas to a value you're comfortable funding from
your Purple Flea wallet balance.
Full Platform
All six Purple Flea services available in your cluster
Every Purple Flea service is accessible from any Kubernetes pod via HTTPS. No VPN,
no peering, no cluster-internal deployment required.