Deploy a container

You point a web service at a container image reference, set the port, and Koo pulls the image and rolls it out as a new deployment. Prefer not to build the image yourself? Deploy from Git, deploy straight from your machine with koo up, or let your coding agent do it — deploys with AI work the same way.

What you need

• An OCI image pushed to a registry (Docker Hub, GHCR, or any other registry), referenced as registry/name:tag — for example ghcr.io/acme/web:1.4.2.
• The TCP port your server listens on inside the container.
• A project and environment to deploy into. If you don't have one yet, the quickstart walks through creating your first.

Image deploys skip the build phases entirely: the deployment goes from queued straight to applied, and Koo's hosting layer pulls your image as-is.

Deploy from the console

1. Open the environment — its canvas shows each service as a node.
2. Click New service (or right-click the canvas) and choose Docker Image.
3. Paste the image reference and click Add service.
4. The new service appears as a staged node. Click it to open its drawer and check that Port in the Settings tab matches the port your server listens on (new services default to 8080).
5. Press Deploy on the changes bar (or Shift+Enter).

Nothing is created until you press Deploy — creates and edits on the canvas are staged changes. Once the deploy is applied, the previous version keeps running until the new one is up, and the live state of the service is always visible on its status. You can also trigger image deploys programmatically through the Deployments API.

Public and private images

Public image references work as-is — no credentials needed. For a private image, add registry credentials to the service — see Pull from a private registry; it is available on every plan.

Redeploying a new tag

To ship a new release, push the new tag to your registry, then update the service's image reference — the change deploys the new image. The update happens through the services API: in the console, a service's source is fixed once it is created. Every deploy creates a new immutable version — nothing is mutated in place, and you can roll back to any earlier version.

Prefer a unique tag per release (a version number or commit SHA) over reusing a mutable tag like latest, so each deployment maps to a known image.

Troubleshooting

Image pull fails. When the image can't be pulled, the service's status reports an image_pull_failed error carrying the registry's own reason. Check the reference for typos, confirm the tag exists in the registry, and — for a private image — confirm the registry credentials are set and still valid.

Wrong architecture. Koo runs linux/amd64 containers. An image built only for arm64 (the default on an Apple Silicon machine) will fail to start — rebuild with docker build --platform linux/amd64 . or publish a multi-arch image.

Crash loop. If the deployment reaches applied but the service doesn't come online, the container is likely exiting on boot. Check the service's logs for the startup error, confirm the port you set matches what the server actually binds, and confirm any required variables are set.