On this page
- 01What you'll set up
- 02What runs where
- 03Register an edge instance
- 04Deploy with Helm
- 05Deploy with Docker Compose
- 06Confirm the first heartbeat
- 07Add an Edge BYOK credential
- 08Govern edge traffic
- 09How budgets work across several edges
- 10What the edge does without the cloud
- 11Optional: a local semantic cache
- 12Health and metrics
- 13If something goes wrong
01
What you'll set up
Some workloads must keep provider keys and prompts inside your own network. The edge gateway is the Cloptima gateway running in your VPC. In about twelve minutes you will register it, deploy it, connect a provider key that never leaves your hosts, and confirm that policy and reporting work.
- An edge instance registered in Cloptima
- The edge gateway running in your Kubernetes cluster or on a Docker host
- An Edge BYOK credential whose key stays on your side
- A virtual key and policy that govern edge traffic
You need an owner or admin role and a place to run containers inside your network.
02
What runs where
The cloud keeps the control plane. The edge handles your requests.
| In Cloptima's cloud | In your network, on the edge gateway |
|---|---|
| Policies, bindings, and virtual keys are authored here | Your requests are received and governed |
| Reports, the Explorer, and the audit log | Your provider keys are held and used |
| Signed policy and pricing sent to the edge | Budgets, rate limits, and guardrails are enforced locally |
| Each policy budget and the org-wide ceiling, shared by every gateway | A share of that budget, enforced locally and topped up in the background |
| Usage events received from the edge | Prompts and answers stay in your network, unless you turn on trace retention in a policy |
03
Register an edge instance
Registration gives the edge gateway an identity and a token.
- 1
Open Edge Instances
Go to AI → Credentials & Keys and find the Edge Instances card.
- 2
Choose + Register Edge
Enter an Instance Name such as prod-vpc-eu, a Region, and an Environment.
- 3
Copy the edge token
It is shown once. Store it in your secret manager.
- 2Instance Name *
- prod-vpc-eu
- 2Region
- eu-west-1
- 2Environment
- production
04
Deploy with Helm
On Kubernetes, one command installs the edge gateway.
helm upgrade --install cloptima-edge oci://ghcr.io/cloptima/charts/cloptima-edge-gateway \
--namespace cloptima --create-namespace \
--set edge.pat="$CLOPTIMA_EDGE_PAT" \
--set edge.controlPlaneUrl="https://api.cloptima.ai" \
--set redis.embedded.enabled=true- edge.pat takes the token, or use edge.patSecret.name to read it from a Kubernetes secret
- redis.embedded.enabled bundles the storage the edge needs; use redis.url to bring your own
- semanticCache.enabled adds the optional local semantic cache
05
Deploy with Docker Compose
On a VM or a Docker host, download the production compose file and start it.
curl -fsSL https://api.cloptima.ai/v1/edge/docker-compose.yml -o docker-compose.yml
cat > .env << 'EOF'
CLOPTIMA_EDGE_PAT=<your-edge-token>
CLOPTIMA_EDGE_CONTROL_PLANE_URL=https://api.cloptima.ai
EOF
docker compose up -dThe compose file starts the edge gateway and the storage it needs. If you run the processes yourself, the console's deploy assistant lists the environment variables to set.
06
Confirm the first heartbeat
The console shows when your edge gateway has connected.
- 1
Watch the deploy assistant
It waits for the first heartbeat after you deploy.
- 2
Read the Heartbeat column
The Edge Instances card shows the status and the last heartbeat time.
- 3
Use Check Now
If nothing arrives, confirm the container is running and can reach the control plane URL.
07
Add an Edge BYOK credential
The credential record lives in Cloptima. The secret lives only on your host.
- 1
Choose + Add Credential
On the Provider Credentials card.
- 2
Choose Storage Mode: Edge BYOK (Stay in Your VPC)
Pick the Edge Instance it belongs to.
- 3
Enter a Key Reference ID
A short name such as my-openai-prod.
- 4
Save
Cloptima stores the record with no secret.
- 5
Set the key on the edge host
Set CLOPTIMA_KEY_ followed by the reference id, in capitals, to the key. For Bedrock, also set CLOPTIMA_SECRET_ACCESS_KEY_ with the same suffix to the secret access key. For Vertex AI, set CLOPTIMA_SERVICE_ACCOUNT_JSON_ to the service-account JSON instead.
# Reference ID: my-openai-prod
export CLOPTIMA_KEY_MY_OPENAI_PROD=<your-api-key>08
Govern edge traffic
Policies and keys work the same way as in the cloud.
- Create a virtual key and send requests to your edge gateway's address instead of the cloud address
- Bind a policy to the key, or to its team, app, and environment
- Budgets, rate limits, tool rules, guardrails, and caches apply on the edge
- The org baseline policy applies on the edge as it does in the cloud
- Usage reaches your reports through the edge's uploads
Policy changes reach the edge in about a second.
09
How budgets work across several edges
Edge gateways do not get budgets of their own. A policy's daily and monthly budget, and the org-wide ceiling on the baseline policy, are shared by the cloud gateway and every edge gateway in your organization. Each edge spends from a share of that budget.
| When | What the edge does |
|---|---|
| A new UTC day starts under a blocking budget | Receives a share of the remaining budget from Cloptima |
| Requests that fit the share | Admits them locally, with no call to the cloud |
| The share runs low | Asks for more in the background |
| Every 30 seconds or so | Reports what it spent, so the shared budget stays current for every other gateway |
| The UTC day ends | Closes the day's share at what it actually spent. Unused room returns to the monthly budget |
Cloptima sizes each share from the room left in the budget and never grants more than that room. The cloud gateway and all your edges therefore stay within one budget, wherever the traffic runs. A budget set to Alert only needs no share: the edge counts the spend and reports it.
10
What the edge does without the cloud
A cloud outage does not stop your traffic. The edge keeps serving for up to 24 hours on its last signed policy and pricing.
| Situation | What the edge does |
|---|---|
| The control plane is unreachable | It keeps serving on its last signed policy and pricing for up to 24 hours, and stays ready |
| Budgets | It keeps admitting requests within the budget share it holds. Past that share, the org baseline setting "Keep serving if an edge gateway loses contact with Cloptima" decides, and a policy can turn serving off for its own apps. On, the default: requests continue, the spend is counted on the edge and applied to your budgets when it reconnects. Off: requests that need more budget are refused |
| Usage events | They are kept safely on the edge and uploaded when the connection returns |
| Audit | Your audit log records when the edge lost contact and when it reconnected |
| Out of contact for more than 24 hours | The edge refuses requests and reports itself not ready until it reconnects |
11
Optional: a local semantic cache
The edge can run the semantic cache next to your traffic.
Turn on semanticCache.enabled in the Helm chart, or use the semantic profile in the compose file. Without it, the exact cache still works.
12
Health and metrics
The edge exposes the endpoints your platform team expects.
| Endpoint | Use it for |
|---|---|
| /healthz | Liveness: the process is running |
| /readyz | Readiness: the edge holds current signed state and can serve |
| /status | A summary of the edge's state |
| /metrics | Prometheus metrics, prefixed cloptima_edge |
13
If something goes wrong
Most problems are connectivity or the key reference.
| What you see | Likely cause | Fix |
|---|---|---|
| No heartbeat | The edge cannot reach the control plane, or the token is wrong | Check the control plane URL, outbound access, and the token |
| Requests fail with a missing credential | The key environment variable is not set on the host | Set CLOPTIMA_KEY_ plus the reference id in capitals |
| /readyz fails | The edge holds no current signed policy: it has been out of contact for more than 24 hours, Cloptima refused its token or instance, or its policy could not be refreshed | Restore the connection to the control plane, then check the edge token and instance in the console |
| Spend is missing in reports | Uploads are waiting for connectivity | Check outbound access; they resume on their own |
| Cloptima credits are refused | The edge only uses your own keys | Add an Edge BYOK credential |
| 503 edge_budget_lease_unavailable | The edge used its budget share while it cannot reach Cloptima, and the org baseline or the policy does not keep serving offline | Restore outbound access to the control plane, or turn on keep serving in the org baseline and clear Stop serving on the policy |