# Quickstart for Depot Registry (https://depot.dev/docs/registry/quickstart)

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](/docs/cli/reference/overview) on your machine to work with Depot Registry from your terminal.

* **macOS**

  ```shell
  brew install depot/tap/depot
  ```

* **Linux**

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

* **All platforms**

  Download the binary file for your platform from the [Depot CLI releases page](https://github.com/depot/cli/releases) 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](/orgs) 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](/docs/cli/authentication) for details on generating these tokens.

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

```shell
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:

```shell
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:

```shell
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](#authenticate-to-the-registry) with `docker login`, then pull using the full image reference:

```shell
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:

```shell
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:

```shell
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:

```shell
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](/blog/now-available-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.

## For AI Agents

The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.