Control Plane Images

Every org gets a private registry at ORG.registry.cpln.io — a standard Docker registry (docker login/push/pull/search all work). Pushing a tag automatically creates an image resource named NAME:TAG in the org (read-only repository, tag, digest, manifest fields; only metadata tags are editable). An image resource is never created directly — POST /org/ORG/image returns 403 "You can create an image only by pushing" — but a build can run on Control Plane instead of local Docker (cpln image build --remote), which is the answer whenever there is no Docker daemon. The recurring failures are a wrong reference form, a non-linux/amd64 image (exec format error), and a missing or mismatched pull secret.

Image references

• "Image name" always includes the tag (my-app:v1.0); a missing tag means :latest. Name and tag each max 128 chars; at most two : (the second only for a registry port); digest pinning NAME@sha256:HEX is supported.
• Link references (/...) must point into the same org — other orgs are reached only via their registry hostname, which is why they need a pull secret.

Build and push

--name NAME:TAG is required — the command aborts without a tag. Everything else follows from where the build runs: no Docker daemon on this machine or runner means --remote.

Both need create on image in the target org. Rejected with `--remote`: --dockerfile, --builder/-B, --buildpack/-b, --env, --env-file, --trust-builder, --trust-extra-buildpacks, --platform, --push. Remote-only (they error without --remote): --repo, --branch, --detach.

Remote builds (--remote)

cpln image build --name my-app:v1.0 --remote --org my-org                      # upload and build the current folder
cpln image build --name my-app:v1.0 --remote --repo https://github.com/o/a --branch main
cpln image build --name my-app:v1.0 --remote --detach                          # returns a build id, does not watch

• Folder upload honors .dockerignore at the folder root, or .gitignore when there is no .dockerignore. Caps: 500 MB, 20,000 files, 20,000 directories. .git, node_modules, __pycache__, .venv, venv, .mypy_cache, .pytest_cache, .ruff_cache, .DS_Store, Thumbs.db, desktop.ini are always excluded (re-include with a ! rule); Dockerfile and .dockerignore are force-included. A symlink pointing outside the folder fails the build. Rebuilds of the same image NAME upload only changed files — --no-cache forces a full re-upload.
• `--repo` takes `github.com` and `gitlab.com` HTTPS URLs only. An SSH remote or a URL with embedded credentials is rejected; any other host needs [email protected].
• A private repo builds through the org's git connection, set up once. The first build that needs it opens a browser to an authorization URL and then continues on its own; in a non-interactive shell the CLI prints the URL and exits — authorize, then re-run. The link is single-use and expires shortly. Later builds are silent.
• Watching is not the build. Logs stream until the push. Ctrl+C stops watching and the build keeps running remotely — check it with cpln image get NAME:TAG. The CLI also gives up watching after 20 minutes, which is not a failure either.

Builds over MCP

deploy_app and build_image build from a repository or from app files stored with write_app_files (the create-app skill); a folder on the user's machine needs the CLI. Every image the build service pushes carries provenance tags: builder.cpln.io/source (app-files, folder, or repository), builder.cpln.io/repo, builder.cpln.io/build, and builder.cpln.io/digest. An image without them was pushed outside a Control Plane build; get_app_files reads them to say where an app's code lives.

Local builds

cpln image build --name my-app:v1.0 --push --org my-org   # reference as //image/my-app:v1.0

--push configures registry auth itself (no separate login step) but hard-errors unless docker-credential-cpln is on PATH (installed with the CLI). For a Docker-native flow instead:

cpln image docker-login --org my-org   # registers the docker-credential-cpln helper in ~/.docker/config.json
docker buildx build --platform=linux/amd64 -t my-org.registry.cpln.io/my-app:v1.0 .
docker push my-org.registry.cpln.io/my-app:v1.0

docker-login stores no secret — Docker resolves a live token from CPLN_TOKEN or the profile on every call. Daemonless CI builders (kaniko, buildah) can also push straight to the registry — it accepts any OCI client with username the literal string `<token>` and a service-account key as password (gitops-cicd skill). All images must be `linux/amd64`; nothing checks the architecture at push or deploy — a wrong-arch image fails at container start with exec format error.

Buildpacks (local builds only)

--remote detects and builds the source itself and never runs pack, so nothing here applies to it. Default builder heroku/builder:24_linux-amd64. A Procfile (one line: web: START-COMMAND) defines the start command; servers must bind 0.0.0.0 and listen on $PORT.

Pulling

• Same org: automatic. The platform injects a managed default-registry credential into every GVC namespace — never create a pull secret for your own org's images.
• Public images: no setup.
• Private registries (including other Control Plane orgs): attach a secret to the GVC at spec.pullSecretLinks — it applies to all workloads in the GVC; there is no per-workload attachment. Only three secret types work as pull secrets: docker (Docker Hub, GHCR, ACR, GAR, other Control Plane orgs — matched to images by registry host in its auths), ecr (its repos list must contain the image's repository; credentials are exchanged for ECR tokens and refreshed automatically), and gcp (matched only for images under its own project: gcr.io/PROJECT/... or REGION-docker.pkg.dev/PROJECT/...).
• Failures are silent: a linked secret of the wrong type, or one that fails to materialize, is skipped at deploy with no configuration-time error — the symptom is only an image-pull failure on the replica.

Attach with mcp__cpln__update_gvc (pullSecretLinks is merged with existing links; removePullSecretLinks removes; an empty list clears all). The registry secret (docker, ecr, or gcp) comes from create_secret with values: "user"; for another Control Plane org the docker username is the literal <token> and the password a service-account key. CLI fallback: cpln gvc update GVC --set 'spec.pullSecretLinks+=//secret/NAME' --org ORG. The full cross-org setup (source-org service account, pull policy, target-org secret, GVC) is in the environment-promotion skill; cpln image copy NAME:TAG --to-org ORG2 [--to-name NEW] [--to-profile P] [--cleanup] is the one-time alternative — it docker-logins both orgs, then pulls, retags, and pushes through the local Docker daemon (needs pull on the source, create on the destination).

Permissions

view is read-only; manage implies all of the above.

Registry authorization is repository-granular. When the registry checks a docker push or pull it evaluates the permission against REPOSITORY:* (tag wildcarded, no resource link) — so a policy whose targetLinks list specific NAME:TAG images never authorizes a docker push or pull. Scope registry policies to all images, or use a targetQuery on the repository property (mcp__cpln__create_policy with targetKind: image; image queries support name, id, tag, digest, repository, created, lastModified). Tag-specific targetLinks only gate API operations on that image record (view/edit/delete).

Tags, digests, and redeployment

Pushing an existing tag again updates the same image resource (new digest, same name) — but running workloads do not follow it by default:

• `supportDynamicTags: false` (default): the reference is resolved at container start. Serverless pods pull on every start; standard/stateful/cron pods may reuse a node-cached image for any non-latest tag — so cpln workload force-redeployment after a same-tag push is not guaranteed to pick up the new content on every node.
• `supportDynamicTags: true`: the platform re-resolves every container tag to a digest about every 5 minutes and on each workload change, records the result in status.resolvedImages (digest, per-platform manifests, errorMessages), and when a digest changes patches the workload — rolling out new pods pinned to IMAGE@sha256:.... Digest-pinned references are skipped.

For production, prefer immutable tags (commit SHA, semver) or digest pinning; reserve supportDynamicTags for dev/staging convenience.

CLI subcommands

build, copy, docker-login, get [REF...] (no ref lists all), delete REF..., edit, patch, query (--prop repository=my-app), tag (metadata key=value tags on the image resource, NOT docker version tags), permissions, access-report, audit. There is no `cpln image push` or `pull` — push via build --remote, build --push, or docker push after docker-login. `copy` has no `--remote` mode and still needs a local Docker daemon. Verify flags with cpln image SUBCOMMAND --help before authoring commands.

Verify

• After a push: mcp__cpln__get_resource (kind="image", name="NAME:TAG") — check digest and lastModified; mcp__cpln__list_resources (kind="image") to list.
• After a workload image change: mcp__cpln__list_deployments for per-location readiness; with dynamic tags, inspect status.resolvedImages via mcp__cpln__get_resource (kind="workload") for errorMessages and the resolved digest.
• After a detached or interrupted remote build: cpln image get NAME:TAG --org ORG; the image appears only once the build pushes. mcp__cpln__get_image_build reads a build's status and log by id; pass waitSeconds to wait for it instead of reading it again and again.
• CLI fallback (CI/CD): CPLN_TOKEN + cpln image get NAME:TAG --org ORG -o json.

Troubleshooting