Registries

Registries hold the credentials Daytona uses to pull images from private container registries. A registry credential is a username and a password or token for one registry host. A project holds at most one credential per host, matched by the host in the image reference.

Stored credentials apply to registry images. Daytona uses the credential to import a registry image and to pull it again for a Linux or GPU sandbox. Pulls from a host without a credential, and the base image of a Dockerfile build, are anonymous and work only for public images. Windows and macOS sandboxes ignore stored credentials.

Registry credentials work with GitHub Container Registry, Docker Hub, Google Artifact Registry, Amazon ECR, and any registry that accepts HTTP Basic authentication. Daytona encrypts the password or token at rest and never returns it. The provider kinds check the host when you store the credential, so a credential stored for the wrong host fails at that point instead of at pull time.

1. You store a credential for a registry host: the host, a kind (basic, ghcr, gcr, or ecr), a username, and a password or token. The ghcr, gcr, and ecr kinds validate the host, so a misconfigured credential fails at write time rather than silently at pull time.
2. Daytona takes the host from the registry reference of an image import. A sandbox create takes a registered image name or ID; when the image was imported from a registry and is not present in the target region, Daytona pulls it again from that image's registry reference.
3. If a credential is stored for that host, the pull authenticates with it; otherwise the pull is anonymous. No opt-in is needed on individual requests.
4. To rotate a credential, store the same host again with the new password. The update replaces the credential in place and takes effect on the next pull.

A registry credential has the following fields:

Use cases

Registry credentials are used when the images that sandboxes boot from are not public.

• Private application images: images that a CI pipeline builds and pushes to a private registry are imported and boot in sandboxes.
• Images in a cloud provider's registry: images stored in Amazon ECR or Google Artifact Registry are pulled with that provider's access keys, such as an AWS access key or a service account JSON key.
• Private Docker Hub repositories: a credential stored for Docker Hub also applies to image references without a host, such as my-org/my-image.
• Self-hosted registries: any registry that accepts HTTP Basic authentication works with a basic credential for its host.
• Sandboxes in other regions: a sandbox created in a region that does not have the image yet pulls it again from the registry with the stored credential.
• Credential rotation: a leaked or expired token is replaced in place, and the next pull uses the new one with no change to images or sandboxes.
• Early credential checks: the ghcr, gcr, and ecr kinds validate the host when the credential is stored. A credential for the wrong host fails at that point instead of at pull time.
• Team access without shared tokens: a credential is stored once per host for the whole project, and its token is encrypted and never returned. Team members import private images without holding the token.

Container registries

Store a credential for a registry host. Storing a credential for a host that already has one replaces the stored credential. Daytona encrypts the password at rest, and reads return only the host, kind, username, description, and last update time.

1. Go to Daytona Registries ↗
2. Click Add Registry
3. Enter the following details:
   • Host: the registry host, as host[:port]
   • Kind: the registry kind: Basic (username + password), GitHub Container Registry, Google Container Registry, or Amazon ECR
   • Username: the registry username
   • Password / Token: the registry password or token
   • Description: an optional description
4. Click Add

printf %s 'YOUR_REGISTRY_PASSWORD' | daytona registry set YOUR_REGISTRY_HOST \
  --username YOUR_REGISTRY_USERNAME \
  --password-stdin

Host in the request body

Store a credential with the host in the request body instead of the URL path. The request accepts the same fields and behaves the same way as the path form.

curl 'https://api.daytona.com/registries' \
  --request PUT \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "host": "ghcr.io",
  "kind": "ghcr",
  "username": "YOUR_GITHUB_USERNAME",
  "password": "YOUR_GITHUB_PAT",
  "description": "CI pull token"
}'

GitHub Container Registry

printf %s 'YOUR_GITHUB_PAT' | daytona registry set ghcr.io \
  --kind ghcr \
  --username YOUR_GITHUB_USERNAME \
  --password-stdin

Docker Hub

Store a credential for Docker Hub. Daytona stores Docker Hub credentials under the host index.docker.io. The hosts docker.io, registry-1.docker.io, and registry.hub.docker.com refer to the same credential, and image references without a registry host, such as python:3.12, use it.

printf %s 'YOUR_DOCKERHUB_TOKEN' | daytona registry set docker.io \
  --username YOUR_DOCKERHUB_USERNAME \
  --password-stdin

Google Artifact Registry

# The password is the service account JSON key
daytona registry set us-docker.pkg.dev \
  --kind gcr \
  --username _json_key \
  --password-stdin < service-account-key.json

Amazon ECR

Store AWS access keys for an Amazon ECR registry. Daytona checks the keys with AWS STS on store and refuses keys that AWS rejects or that belong to an account other than the host's. A failed check leaves any existing credential for the host unchanged.

printf %s 'YOUR_AWS_SECRET_ACCESS_KEY' | daytona registry set AWS_ACCOUNT_ID.dkr.ecr.AWS_REGION.amazonaws.com \
  --kind ecr \
  --username YOUR_AWS_ACCESS_KEY_ID \
  --password-stdin

Use private registry images

Import a private image into the project, then create sandboxes from it by name. The import authenticates with the credential stored for the host in the image reference. A Linux or GPU sandbox create takes a registered image name or ID, which must be ready first.

from daytona import Daytona

daytona = Daytona()

# The pull authenticates with the credential stored for ghcr.io
image = daytona.v2.images.pull("ghcr.io/acme/private-runtime:latest", name="private-runtime")

# The pull returns once it is queued; each wait returns after 30 seconds at most
while image.status not in ("ready", "failed"):
    image = daytona.v2.images.get(image.id, wait="ready")
if image.status == "failed":
    raise RuntimeError(image.error)

sandbox = daytona.v2.create("private-runtime")

Operations

List registries

daytona registry list

Get a registry

daytona registry get ghcr.io

Delete a registry

Delete the credential for a registry host. Later pulls from that host are anonymous.

daytona registry delete ghcr.io