Run One-off Workloads - Control Plane

The cpln workload run command creates a temporary workload, waits for it to become healthy, executes your command, and optionally cleans up. It’s similar to docker run - perfect for one-off tasks, debugging, and running scripts in your cloud environment.

Recommendation: Consider using cpln workload cron run instead — it’s significantly faster and the preferred way to run commands going forward. It uses a persistent cron workload runner that is reused across executions, eliminating the overhead of creating and tearing down a workload each time.

When to use this

Run migrations

Execute database migrations in your production environment

One-off scripts

Run maintenance scripts, data processing, or cleanup tasks

Debug with clones

Clone an existing workload to debug in an isolated environment

Quick tests

Spin up temporary containers to test configurations

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Required permissions

You need create and exec permissions on workloads. See Workload Permissions.

Basic usage

cpln workload run -- <command> [args...]

By default, this:

Creates a temporary workload using ubuntu:22.04
Waits for it to become healthy
Executes the command
Exits (workload remains unless --rm is used)

Options

Option	Description
`--clone`	Clone an existing workload instead of using the default image
`--image`	Use a custom image
`--rm, --remove`	Delete the workload after the command completes
`-i, --interactive`	Keep the session open after command execution
`--container`	Target container (when cloning multi-container workloads)
`--cpu`	CPU allocation (e.g., `50m`, `100m`)
`--memory, --mem`	Memory allocation (e.g., `128Mi`, `256Mi`)
`--shell, -s`	Shell to use for interactive mode (default: `bash`)
`--location`	Target location
`--tag`	Add tags to the temporary workload
`-c, --command`	Override container command
`-a, --arg`	Override container args

Run a simple command

cpln workload run -- echo "Hello from Control Plane!"

Use a custom image

cpln workload run --image python:3.11 -- python --version

Clone an existing workload

Run commands in an environment identical to an existing workload:

cpln workload run --clone my-app -- npm run migrate

This clones my-app with all its configuration (env vars, secrets, identity) and runs the command.

Target a specific container

For multi-container workloads:

cpln workload run --clone my-app --container worker -- python process.py

Automatic cleanup

Delete the temporary workload after the command completes:

cpln workload run --rm -- echo "Hello from Control Plane!"

Use --rm for one-off tasks to avoid accumulating temporary workloads.

Interactive mode

Stay in the container after the command runs:

cpln workload run --interactive -- ls -la

After the command executes, you’ll have an interactive shell to continue working.

Specify a shell

cpln workload run --interactive --shell sh -- cat /etc/os-release

Common workflows

Run database migrations

cpln workload run --clone my-app --rm -- npm run db:migrate

Debug in a cloned environment

cpln workload run --clone production-api --interactive -- bash

Run data processing

cpln workload run \
  --image python:3.11 \
  --cpu 500m \
  --memory 1Gi \
  --rm \
  -- python /scripts/process-data.py

Test in a specific location

cpln workload run --location aws-eu-central-1 -- curl -s https://api.example.com

Add tags for tracking

cpln workload run --tag job=nightly-backup --tag env=prod --rm -- ./backup.sh

Resource configuration

Override CPU and memory for resource-intensive tasks:

cpln workload run \
  --cpu 200m \
  --memory 512Mi \
  -- ./heavy-computation.sh

Override container command

Replace the container’s default command:

cpln workload run \
  --image myapp:latest \
  --command sleep \
  --arg "infinity" \
  --interactive \
  -- bash

This starts the container with sleep infinity instead of its default command, then opens a bash session.

Troubleshooting

Workload never becomes ready

Run with --verbose to see what the platform reports about the deployment while the command waits:

cpln workload run --verbose -- echo hello

Each time the reported status changes, it is written to stderr — naming the containers that are not ready yet and any message the platform attached, such as a deployment paused because it cannot reveal a referenced secret, or an image that cannot be pulled.If the status shows nothing unusual, the location may not be available in your GVC:

cpln gvc get my-gvc

Verify the location is in the GVC’s staticPlacement.locationLinks.

Command not found

The default Ubuntu image may not have your tool. Use a custom image:

cpln workload run --image node:20 -- npm --version

Shell not available

Specify a different shell:

cpln workload run --interactive --shell sh -- echo "done"

Timeout waiting for workload

The workload may take longer to start. Check the GVC locations and image availability.The error names the last status the platform reported, which usually identifies the container that never became ready. Run with --verbose to follow that status from the start of the wait.

Next steps

Execute Commands

Run commands in existing workloads

Connect to Workloads

Interactive shell in running workloads

Create a Workload

Create persistent workloads

Command Reference

Full run command reference

​When to use this

Run migrations

One-off scripts

Debug with clones

Quick tests

​Prerequisites

​Basic usage

​Options

​Run a simple command

​Use a custom image

​Clone an existing workload

​Target a specific container

​Automatic cleanup

​Interactive mode

​Specify a shell

​Common workflows

​Run database migrations

​Debug in a cloned environment

​Run data processing

​Test in a specific location

​Add tags for tracking

​Resource configuration

​Override container command

​Troubleshooting

​Next steps

Execute Commands

Connect to Workloads

Create a Workload

Command Reference

When to use this

Prerequisites

Basic usage

Options

Run a simple command

Use a custom image

Clone an existing workload

Target a specific container

Automatic cleanup

Interactive mode

Specify a shell

Common workflows

Run database migrations

Debug in a cloned environment

Run data processing

Test in a specific location

Add tags for tracking

Resource configuration

Override container command

Troubleshooting

Next steps