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, a username, and a password or token. The GitHub, Google, and Amazon 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.

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. The import authenticates with the credential stored for the host in the image reference. No opt-in is needed on individual requests.

• 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. For Amazon ECR, Daytona checks the keys with AWS STS when you store them. It refuses keys that AWS rejects or that belong to another account.

• Self-hosted registries. Any registry that accepts HTTP Basic authentication works with a basic credential for its host. The host is a bare host[:port], with no scheme or path. Without a stored credential, pulls from the host are anonymous and work only for public images.

• 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. To rotate, store a credential for the same host again with the new password or token. The API replaces the whole credential on each request, so an omitted kind resets to basic.

• 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. Reads return only the host, kind, username, description, creation time, and last update time.

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, creation time, 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

A registry credential has the following fields:

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

GitHub Container Registry

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

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

Permissions

Registry credentials are scoped to a project. Access is governed by three permissions, which you can grant to an organization role or an API key.

The audit logs record credential stores, updates, and deletes.