Quickstart for Depot Registry

Get started with the Depot Registry to store container builds, images or any other OCI-compliant artifacts.

Install the Depot CLI

Install the Depot CLI on your machine to work with Depot Registry from your terminal.

macOS
```
brew install depot/tap/depot
```

Linux

curl -L https://depot.dev/install-cli.sh | sh

All platforms

Download the binary file for your platform from the Depot CLI releases page in GitHub.

Authenticate to the registry

Each Depot organization has its own registry subdomain:

{orgId}.registry.depot.dev

You can copy your org ID from the sidebar in the Depot dashboard or run depot org list in your terminal.

To authenticate, use docker login with a Depot access token. The registry accepts user, project, organization, trust relationship, and pull tokens. See authentication methods for details on generating these tokens.

Set the username to x-token and the password to your chosen token:

docker login {orgId}.registry.depot.dev -u x-token -p <depot-token>

Note: For depot pull and depot push, the Depot CLI uses your existing CLI credentials to authenticate and docker login isn't required.

Push images to the registry

There are two ways to get images into Depot Registry: push an existing image with Docker, or save a build directly from depot build.

With `docker push`

Tag the image with your org subdomain and the repository name and tag you want, then push:

docker tag <local-image> {orgId}.registry.depot.dev/your/app:v1
docker push {orgId}.registry.depot.dev/your/app:v1

Repositories are created automatically on first push.

With `depot build`

Save build output directly to the registry using the --save flag:

depot build --save --save-tag my-image .

The --save-tag flag is optional but useful for referencing the image by name instead of build ID.

Pull images from the registry

With `docker pull`

Make sure you've authenticated with docker login, then pull using the full image reference:

docker pull {orgId}.registry.depot.dev/your/app:v1

With `depot pull`

The CLI authenticates with your existing Depot credentials so docker login isn't required. Specify a build ID or tag:

depot pull --project <your-project-id> <build-id>
depot pull --project <your-project-id> my-image

Omit the build ID or tag to display an interactive list of builds to choose from.

With Kubernetes

Create an image pull secret with your Depot token:

kubectl create secret docker-registry regcred \
  --docker-server={orgId}.registry.depot.dev \
  --docker-username=x-token \
  --docker-password=<any project, org, or user access token>

Then reference the secret in your pod spec using imagePullSecrets.

Copy images to another registry

Use depot push to copy a saved build from Depot Registry to another registry. Authenticate to the target registry with docker login first, then run:

depot push --project <your-project-id> -t <your-image-registry>:<tag> <build-id>

The transfer happens directly from Depot infrastructure to your target registry, skipping your local machine.

Backward compatibility

Depot Registry v2 is backward compatible with v1. If you're already using the Depot Registry, you don't need to change anything. Existing project-scoped URLs and build tags continue to work:

registry.depot.dev/<project-id>:<build-id>

Use the org-subdomain format ({orgId}.registry.depot.dev) for new repositories and for using the registry as a primary registry with custom names.