Usage Examples - Control Plane

These prompts work in every compatible tool. Describe the outcome and let the assistant pick the tools; name your org, GVC, and resources so it never has to guess. A few examples need a larger toolset profile and say so. Everything else works on the default core profile, which is also what the Claude and ChatGPT directory listings use.

Setting Context

Before performing operations, set your organization and GVC context:

Use org "my-org" and gvc "my-gvc" for the following operations.

Set my Control Plane context to organization "my-org" and GVC "my-gvc".

Setting context once at the start of a conversation helps the AI assistant understand which resources to target. The server keeps no state between calls, so the assistant passes that org and GVC on every call it makes.

Build and Deploy Apps

Create an App from Scratch and Deploy It

Describe the app you want. The assistant writes the code, stores it on Control Plane under the app’s name, builds it into an image in your org’s private registry, deploys it as a public workload, and reports the URL together with a link to download the source. No git repository, Docker daemon, or file on your machine is involved. For an app that keeps anything, such as a portfolio, a blog, or a shop, the assistant first asks what your request leaves open, with its recommendations, and builds what you choose. If your org has no GVC yet, it recommends a location near your users and creates one where you choose.

Create me a small Flask app that shows a random quote on each refresh and
deploy it to org "my-org". Give me the URL and the source code when it is up.

Have a logo or other files of your own? The assistant returns an upload link; drop the files on it and they become part of the app under the paths the assistant chose. Attach nothing to the chat itself: files attached there cannot reach the app. Later changes go the same way, in this chat or a new one: the assistant finds the app by its name, checks where its code lives, edits the stored files, builds the next tag, and moves the running workload to it. An app built from a repository or pushed by hand is not rewritten: the assistant tells you where its code lives instead.

Change the quote app so the page has a dark theme and a "next quote" button,
then redeploy it.

This is for an app that does not exist yet. An existing image or a repository deploys directly, as shown below, and a database, cache, or queue comes from the Template Catalog. In Claude Code, Codex, Cursor, or another agent with a filesystem and the cpln CLI, the assistant writes the app into a folder on your machine and builds it with cpln image build --remote --dir instead; without the CLI, or in a chat that cannot write files, it stores the files on Control Plane.

Deploy an Existing Image

One call deploys an image as an app with production defaults: health checks, and two replicas so a deploy never takes it offline. The assistant follows the rollout until every location is ready and reports the canonical URL.

Deploy nginx:latest as a public app called "web" on port 80 in GVC
"production" and give me its URL.

Build and Deploy from a Repository

The assistant builds a GitHub or GitLab repository on Control Plane, pushes the image to your org’s private registry, and deploys it, with no Docker daemon or CLI involved.

Build https://github.com/my-org/my-app on the main branch and deploy it as
a public app called "my-app" in GVC "production".

The first build from a private repository returns a one-time authorization link instead of starting: open it, approve access for your organization, then ask the assistant to build again. Later builds run without prompting.

Build a Local Folder

The MCP server cannot read your filesystem, so a folder on your machine builds with the CLI. An agent with a terminal runs cpln image build --remote itself; a chat gives you the command. It still needs no Docker daemon, only the CLI with a profile authenticated to the target organization.

I want to build the app in ./api and deploy it to org "my-org".

Keep Files Across Restarts

A container’s filesystem is wiped on every restart. Ask for storage on the first deploy, because a workload cannot gain its own disk later without being recreated. Per-replica storage runs the app as one replica, which suits SQLite and other single-writer files; shared storage lets every replica read and write the same files, such as uploads.

Deploy //image/notes:v1 as "notes" on port 8080 in GVC "production", and
keep its SQLite files in /data across restarts.

Check Builds and Images

What is the status of build "b-1a2b3c" in org "my-org"? Show me the log if it failed.

Show me all images in org "my-org" with their tags and creation dates.

GVC Operations

Create a GVC

Create a new GVC with specific locations. You can use friendly location names or technical location IDs:

Create a new GVC called "production" with locations in Frankfurt, Virginia, and Oregon.

Create a new GVC called "production" with locations in aws-us-east-1 and aws-eu-central-1.

Create a GVC named "multi-cloud-app" with locations:
- azure-centralus
- gcp-me-west1
- aws-eu-central-1

Create a GVC called "staging" with these settings:
- Description: "Staging environment for QA testing"
- Locations: Frankfurt, Virginia
- Tags: environment=staging, team=platform

Friendly names like “Frankfurt” or “Virginia” resolve against your org’s own location list, which also holds the BYOK locations registered from your own clusters. Name the locations yourself, or tell the assistant to choose: it picks one of your org’s enabled locations and tells you which.

List and Inspect GVCs

Show me all GVCs in the org "my-org".

Get the details of GVC "production" including its locations and configuration.

Workload Operations

Create a Workload

Create a new workload with various configurations:

Create a publicly accessible workload called "api-server" with:
- Image: nginx:latest
- Port: 80
- Memory: 256Mi
- CPU: 250m

Deploy a publicly accessible workload named "web-frontend" with these specifications:
- Container image: httpd:latest
- Exposed port: 80
- Memory: 512Mi
- CPU: 500m
- Min replicas: 2
- Max replicas: 5
- Health check path: /

Create a workload "orders-api" from image //image/orders:v3 on port 8080
that only other workloads in GVC "production" can reach.

Create a cron workload called "data-processor" that:
- Uses image: python:3.11-slim
- Runs every hour (0 * * * *)
- Has 1Gi memory
- CPU: 500m
- Does not need external access

Update and Scale a Workload

Scale workload "api-server" between 3 and 10 replicas per location based on
requests per second.

Update the "web-frontend" workload to use image httpd:2.4-alpine.

Add LOG_LEVEL=info and CACHE_ENABLED=true to workload "api-server", set
DATABASE_PASSWORD from the key "password" of the secret "db-credentials",
and give the workload access to that secret.

A replica range only takes effect with an autoscaling metric. When the workload has none, the assistant sets a fitting one or asks you which. If Terraform or Pulumi manages the workload, the assistant warns you that the next apply can revert the change.

Restart, Roll Back, Promote, or Open a Workload

Each of these is one call: the assistant makes the change, waits for the workload to be ready, and reports the result.

Restart workload "api-server" in GVC "production" so it picks up the new secret values.

The last deploy of "api-server" in GVC "production" broke it. Roll it back to the previous image.

Promote workload "api-server" from GVC "staging" to GVC "production" with image my-app:v2.

Let workload "web" call workload "api-server" inside GVC "production", and tell me the URL it should use.

Run a Cron Job Now or Replace a Stuck Replica

Both have side effects in production, so the assistant confirms before running them.

Run the cron job "data-processor" in GVC "production" now and show me its
logs when it finishes.

One replica of "api-server" in aws-eu-central-1 is stuck. Find it and
replace it.

Check Workload Status

List all workloads in GVC "production" with their current replica counts and status.

Show me the detailed status of workload "api-server" including:
- Current replicas
- Deployment status per location
- Recent events or errors

Delete a Workload

Delete the workload "old-service" from GVC "staging".

Deletion is permanent. The assistant tells you what a deletion removes and what breaks, then waits for your yes. Deleting a GVC removes every workload and identity in it, so the assistant shows that and asks again even when your first message asked for it.

Diagnose and Observe

Diagnose a Failing Workload

One call reads the workload’s deployments, events, and recent error logs, and returns each likely cause with its evidence and the fix.

Why is workload "api-server" in GVC "production" failing? Tell me the cause
and the fix before changing anything.

Query Workload Logs

Show me the last hour of logs for workload "api-server" in GVC "production".

Get logs for workload "api-server" that contain "error" or "panic" in the last 2 hours.

Show logs for the "_accesslog" container of workload "web-frontend" in the last 30 minutes.

Get logs for workload "data-processor" from yesterday between 10:00 and 11:00 UTC.

The get_workload_logs tool builds LogQL queries automatically from structured parameters. A plain text filter matches exactly; ask for a pattern, such as “error or panic”, and the assistant writes the LogQL itself.

Query Metrics and Traces

What was the p95 latency of workload "api-server" in GVC "production" over
the last 6 hours?

Show me the memory use of each replica of "api-server" over the last day,
and whether it is close to its limit.

Find the slowest requests to "api-server" in the last hour and show me where
the time went.

Traces need tracing turned on for the GVC. When a trace search comes back empty, the assistant checks that first.

Check the Audit Trail and Quotas

Who changed workload "api-server" in GVC "production" in the last 24 hours, and when?

Am I close to any quota limit in org "my-org"?

Investigate Production Without Risk

Connect with https://mcp.cpln.io/mcp?toolsets=readonly and the assistant has no tool that can change anything, while metrics, logs, traces, events, the audit trail, and diagnosis all stay available.

In org "my-org", find out why checkout requests got slower since this
morning: compare latency, errors, and recent changes for the workloads in
GVC "production".

Databases and Templates

Add a Database or Cache

The assistant installs PostgreSQL, MySQL, MariaDB, MongoDB, or Redis from the Template Catalog in one call. Control Plane generates the credentials, so no password passes through the chat, and the result lists the connection env values as cpln://secret references for your app.

Add a PostgreSQL database named "app-db" in GVC "production" that workload
"api-server" can connect to, and wire its connection env into the workload.

Add a Redis cache named "sessions" in GVC "production" for workload "web".

Browse and Install Templates

Which templates are available for message queues?

Show me what installing Kafka as "events" in GVC "production" would create,
without installing anything.

Install the latest Kafka template as "events" in GVC "production" with its
default values.

Secret Management

Secret values never pass through the chat. The assistant creates secrets whose values Control Plane generates, hands you a Console link for values only you have, rotates secrets, and wires workload access to them; it never reads, accepts, or repeats a value. Paste a credential into the chat and the assistant will not use it, and will advise you to rotate it.

Do we have a secret called "db-credentials"? List the secrets in my org
and show me its type and tags.

Create a secret "session-keys" with random values for SESSION_SECRET and
CSRF_KEY, then give workload "api-server" access to it.

I need a secret "stripe" that holds my Stripe API key. Give me the link
where I enter it.

Rotate the secret "session-keys" and restart the workloads that use it.

Give the workload "api-server" access to the secret "db-credentials"
as environment variables. Set up the identity, policy, and binding
automatically.

When granting workload access to secrets, describe the desired outcome: the MCP server creates the identity, policy, and workload binding in one step.

Domain Configuration

Name the domain and the workload, and the assistant derives the listener and route. It returns the DNS records to add at your DNS provider; the domain stays pending until they resolve.

Put workload "api-server" in GVC "production" behind api.example.com and
tell me which DNS records to add.

Create a domain "api.example.com" with:
- DNS mode: cname
- Certificate challenge: http01
- Port 443 (http2) routing to workload "//gvc/production/workload/api-server"

Policy & Access Control

Create a policy called "viewer-workloads" that grants "view" permission
on all workloads to the group "//group/developers".

Create a policy called "api-secrets" that grants "reveal" on the secret
"//secret/db-credentials" to the identity
"//gvc/production/identity/api-identity".

Create a service account "ci-deployer" in the group "deployers" and give me
the link where I create its key.

A workload needs reveal to read a secret’s values; use only attaches a secret to a GVC or workload. For a workload, grant_workload_secret_access sets the identity and the policy in one call. The service account key prompt needs the full profile, and the key is shown once, in the Console, never in the chat.

Cloud Access

Get the setup guide for creating an AWS cloud account with:
- Provider: aws
- Cloud account name: my-aws-prod
- AWS account ID: 123456789012
- Role ARN: arn:aws:iam::123456789012:role/cpln-my-org

Get the setup guide for creating a GCP cloud account with:
- Provider: gcp
- Project ID: my-gcp-project-123

Give workload "api-server" in GVC "production" the AWS policy
AmazonS3ReadOnlyAccess through the cloud account "my-aws-prod".

The setup guides and creating the cloud account need the full profile. Granting a workload access through an existing cloud account works on core, with no key passing through the chat.

Infrastructure as Code

Export workload "api-server" in GVC "production" as Terraform, with import
blocks so my state can adopt it.

Export everything in GVC "production" as Terraform.

Convert this Control Plane manifest to Terraform:

kind: workload
name: api-server
spec:
  type: standard
  containers:
    - name: main
      image: nginx:latest
      ports:
        - number: 80
          protocol: http

Resources that Terraform or Pulumi manage carry the tag cpln/managedByTerraform: "true". When the assistant reads or changes one, it tells you that the next apply can revert a change made outside your code.

Managed Kubernetes

These need the mk8s or full profile.

Create a managed Kubernetes cluster "edge" on Hetzner in Falkenstein with
three worker nodes. My Hetzner API token is already in the secret
"hetzner-token".

Add a node pool "batch" with two nodes to the cluster "edge".

Plan Before Executing

Ask for the plan without the change: the assistant answers from the docs, the AI Plugin’s skills when installed, and the API schema, and changes nothing.

I want to deploy a workload with a custom domain from CI. Which cpln
commands would I run? Don't change anything.

Show me the REST endpoint, method, and body for updating a workload's
environment variables. Don't call it.

Complex Workflows

Full Application Deployment

Deploy a complete application stack to Control Plane:

1. Create a GVC called "my-app-prod" in Frankfurt and Virginia.

2. Deploy my image //image/backend:1.0 as "backend" on port 8080, reachable
   only from inside the GVC, with 2 to 5 replicas.

3. Add a PostgreSQL database "app-db" that "backend" can connect to, and wire
   its connection env into "backend".

4. Deploy httpd:latest as the public app "frontend" on port 80 with 2 to 5
   replicas, and give me its URL.

Environment Promotion

Promote workloads "frontend" and "backend" from GVC "staging" to GVC
"production". Show me what differs in production first, then promote them
and give me the production URL when they are ready.

Recover from a Bad Deploy

Workload "api-server" in GVC "production" started failing after the last
deploy. Diagnose it, and if the new image is the cause, roll it back and
confirm it is healthy again.

Next Steps

Tools Reference

Every tool the assistant can call, with its toolset profile

Tool Setup

Configure MCP for your preferred tool

Workload Reference

Learn more about workload configuration options

Policy Reference

Configure permissions for your authorized orgs

​Setting Context

​Build and Deploy Apps

​Create an App from Scratch and Deploy It

​Deploy an Existing Image

​Build and Deploy from a Repository

​Build a Local Folder

​Keep Files Across Restarts

​Check Builds and Images

​GVC Operations

​Create a GVC

​List and Inspect GVCs

​Workload Operations

​Create a Workload

​Update and Scale a Workload

​Restart, Roll Back, Promote, or Open a Workload

​Run a Cron Job Now or Replace a Stuck Replica

​Check Workload Status

​Delete a Workload

​Diagnose and Observe

​Diagnose a Failing Workload

​Query Workload Logs

​Query Metrics and Traces

​Check the Audit Trail and Quotas

​Investigate Production Without Risk

​Databases and Templates

​Add a Database or Cache

​Browse and Install Templates

​Secret Management

​Domain Configuration

​Policy & Access Control

​Cloud Access

​Infrastructure as Code

​Managed Kubernetes

​Plan Before Executing

​Complex Workflows

​Full Application Deployment

​Environment Promotion

​Recover from a Bad Deploy

​Next Steps

Tools Reference

Tool Setup

Workload Reference

Policy Reference

Setting Context

Build and Deploy Apps

Create an App from Scratch and Deploy It

Deploy an Existing Image

Build and Deploy from a Repository

Build a Local Folder

Keep Files Across Restarts

Check Builds and Images

GVC Operations

Create a GVC

List and Inspect GVCs

Workload Operations

Create a Workload

Update and Scale a Workload

Restart, Roll Back, Promote, or Open a Workload

Run a Cron Job Now or Replace a Stuck Replica

Check Workload Status

Delete a Workload

Diagnose and Observe

Diagnose a Failing Workload

Query Workload Logs

Query Metrics and Traces

Check the Audit Trail and Quotas

Investigate Production Without Risk

Databases and Templates

Add a Database or Cache

Browse and Install Templates

Secret Management

Domain Configuration

Policy & Access Control

Cloud Access

Infrastructure as Code

Managed Kubernetes

Plan Before Executing

Complex Workflows

Full Application Deployment

Environment Promotion

Recover from a Bad Deploy

Next Steps