# 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](/docs/deploy/deployments-and-rollback). Prefer not to build the image yourself? Deploy [from Git](/docs/deploy/deploy-from-git), deploy straight from your machine with [koo up](/docs/deploy/koo-up), or let your coding agent do it — deploys [with AI](/docs/deploy/deploy-with-ai) work the same way.

## What you need

- 
- 
-

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. 
2. 
3. 
4. 
5.

Nothing is created until you press Deploy — creates and edits on the canvas are [staged changes](/docs/projects/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](/docs/observability/status). You can also trigger image deploys programmatically through the [Deployments API](/api/deployments).

## 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](/docs/deploy/private-registries); 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](/api/services): 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](/docs/observability/logs) for the startup error, confirm the port you set matches what the server actually binds, and confirm any required [variables](/docs/configuration/variables) are set.