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

  Copy code

• Linux

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

  Copy code

• 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.

Use a registry access token to choose which repositories you can push to or pull from. Follow the steps below to create one. For other credentials and their scope, see Authentication and permissions.

Create a registry access token

You must be an organization owner to create a registry access token in the dashboard.

Registry access tokens are separate from the project-scoped tokens generated by depot pull-token. They can grant access to any repository names you select within the organization.

1. Open Registry settings.
2. Under Registry access tokens, click Add access token.
3. Enter a Name for the token.
4. Set Permission to Push to push and pull images, or Pull for pull-only access.
5. Choose an Expiration: 30, 60, or 90 days, one year, or No expiration.
6. In Repository scopes, enter the Depot repository names, separated by commas. For example, enter your/app for the push and pull examples below, or the name of your pull-through repository.
7. Click Create access token.
8. Copy the token and save it securely. Depot shows the token value only once.

Log in with Docker

Set the username to x-token and enter your token at the password prompt:

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

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.

For a workflow example, see Push an image from Depot CI.

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 a registry access token that has Pull permission for your repository:

kubectl create secret docker-registry regcred \
  --docker-server={orgId}.registry.depot.dev \
  --docker-username=x-token \
  --docker-password=<registry-access-token>

Then reference the secret in your pod spec using imagePullSecrets.

Manage registry access tokens

Choose repository scopes

Scopes match repository names within your organization. Don't include the registry hostname or an image tag.

Separate multiple scopes with commas. The token's permission applies to every scope. Create separate tokens if you need pull-only access to one repository and push access to another.

Revoke a registry access token

Organization owners can view and revoke tokens under Registry access tokens in Registry settings. Open the token's three-dot menu and select Revoke.

To change a token's scopes or replace a lost token, create a new token, update the clients that use it, and revoke the old token.

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.