How to Configure Authentication for Accessing Private Container Registries in OpenSandbox Sandboxes

To access private container registries in OpenSandbox, include an auth object with username and password in the image field of your sandbox creation request; this is supported for the Docker runtime but not yet for Kubernetes.

OpenSandbox is an open-source sandbox environment from Alibaba that enables developers to run isolated workloads using container images. When your images reside in private container registries, you must configure authentication credentials so the platform can securely pull those images. This guide explains how to configure authentication for accessing private container registries within OpenSandbox sandboxes based on the actual implementation in the source code.

Understanding the Authentication Architecture

API Schema and Request Structure

The authentication flow begins with the API schema defined in server/src/api/schema.py. The request model defines an ImageSpec class that contains an optional auth field of type ImageAuth. The ImageAuth class requires username and password parameters, which map directly to Docker registry authentication credentials.

When you submit a CreateSandboxRequest, the server validates that the image.auth object conforms to this schema before processing the sandbox creation.

Docker Runtime Implementation

For Docker-based sandboxes, the authentication logic resides in server/src/services/docker.py. The method _resolve_image_auth() (lines 1603-1614) extracts the auth field from the incoming request and constructs an auth_config dictionary.

This configuration is then passed to docker_client.images.pull() with the auth_config parameter (lines 889-891). The Docker Python SDK uses this map—formatted as {"username": "...", "password": "..."}—to authenticate against the private registry during the image pull operation.

Kubernetes Runtime Limitations

The Kubernetes runtime implementation in server/src/services/k8s/kubernetes_service.py currently lacks support for per-request registry authentication. The method _ensure_image_auth_support() (lines 232-242) explicitly checks for the presence of image.auth in sandbox creation requests.

If authentication credentials are provided for a Kubernetes-based sandbox, the server returns a 400 Bad Request error with the message: "image.auth is not supported in Kubernetes runtime yet."

Step-by-Step Configuration for Docker Runtime

1. Structure Your Authentication Payload

Construct your sandbox creation payload to include the auth object within the image specification. The auth object must contain username and password keys with string values.

{
  "image": {
    "uri": "myprivateregistry.example.com/myproject/secure-image:latest",
    "auth": {
      "username": "myuser",
      "password": "mypassword"
    }
  }
}

2. Send the Create Sandbox Request

Submit the request to the OpenSandbox lifecycle API endpoint. The server validates the schema, extracts the authentication credentials, and prepares them for the Docker runtime.

curl -X POST http://localhost:8080/v1/sandboxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
        "image": {
          "uri": "myprivateregistry.example.com/myproject/secure-image:latest",
          "auth": {
            "username": "myuser",
            "password": "mypassword"
          }
        },
        "entrypoint": ["/bin/bash"],
        "resourceLimits": { "cpu": "500m", "memory": "512Mi" }
      }'

3. Verify Successful Image Pull

If the credentials are valid, the Docker runtime pulls the image and starts the container. If authentication fails, the server returns a 500 error with IMAGE_PULL_FAILED in the error details.

Working with Private Registries in Kubernetes

Current Limitations

As implemented in server/src/services/k8s/kubernetes_service.py, the Kubernetes runtime does not support passing registry credentials through the sandbox creation API. The _ensure_image_auth_support() method explicitly rejects requests containing image.auth with a 400 Bad Request response.

Alternative Approaches

To use private registries with Kubernetes-based sandboxes, you must configure cluster-level authentication:

• Pre-create image pull secrets in the Kubernetes namespace and configure the sandbox to use them via persistent volume claims or custom pod specifications
• Use a public image that does not require authentication
• Configure node-level registry authentication by modifying the container runtime configuration on Kubernetes worker nodes

Code Examples

cURL HTTP Request

The following example demonstrates the complete HTTP request structure for creating a sandbox with private registry authentication:

curl -X POST http://localhost:8080/v1/sandboxes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
        "image": {
          "uri": "myprivateregistry.example.com/myproject/secure-image:latest",
          "auth": {
            "username": "myuser",
            "password": "mypassword"
          }
        },
        "entrypoint": ["/bin/bash"],
        "resourceLimits": { "cpu": "500m", "memory": "512Mi" }
      }'

The server extracts the auth object, builds auth_config = {"username": "...", "password": "..."} and passes it to Docker's pull API.

Python SDK Implementation

When using the OpenSandbox Python SDK, construct an ImageSpec with an ImageAuth object:

from sdks.sandbox.python import SandboxClient, ImageSpec, ImageAuth

client = SandboxClient(base_url="http://localhost:8080", api_key="YOUR_API_KEY")

sandbox = client.create_sandbox(
    image=ImageSpec(
        uri="myprivateregistry.example.com/myproject/secure-image:latest",
        auth=ImageAuth(
            username="myuser",
            password="mypassword"
        )
    ),
    entrypoint=["/bin/bash"],
    resource_limits={"cpu": "500m", "memory": "512Mi"},
)

print("Sandbox ID:", sandbox.id)

The SDK serialises ImageSpec (including auth) into the same JSON payload that the HTTP endpoint expects.

Key Implementation Files Reference

File	Role
server/src/api/schema.py	Defines ImageAuth, ImageSpec, and CreateSandboxRequest (the request model)
server/src/services/docker.py	Resolves authentication via _resolve_image_auth(), pulls images with auth_config
server/src/services/k8s/kubernetes_service.py	Contains _ensure_image_auth_support() which rejects auth for Kubernetes runtime
specs/sandbox-lifecycle.yml	OpenAPI spec describing the auth field for images (lines 653-664)

Summary

• Docker runtime: Pass username and password in the image.auth field of your sandbox creation request; the server automatically injects these credentials into the Docker pull operation via auth_config.
• Kubernetes runtime: Per-request registry authentication is currently unsupported; attempts to provide image.auth result in a 400 Bad Request error.
• Implementation location: Authentication logic resides in server/src/services/docker.py (_resolve_image_auth() and _pull_image()), while the API schema is defined in server/src/api/schema.py.
• Alternative for Kubernetes: Use pre-created image pull secrets at the cluster level or public images without authentication requirements.

Frequently Asked Questions

Does OpenSandbox support authentication for private Docker Hub repositories?

Yes, the Docker runtime supports any private registry that uses standard username-password authentication, including Docker Hub. Include your Docker Hub username and personal access token (or password) in the image.auth object when creating the sandbox. The server passes these credentials to the Docker daemon via the auth_config parameter in docker_client.images.pull().

Why does Kubernetes runtime reject my authentication credentials?

The Kubernetes runtime currently lacks support for per-sandbox registry authentication. According to the source code in server/src/services/k8s/kubernetes_service.py, the _ensure_image_auth_support() method explicitly checks for the presence of image.auth and returns a 400 Bad Request with the message "image.auth is not supported in Kubernetes runtime yet." You must use cluster-level image pull secrets or public images instead.

Can I use access tokens instead of passwords for registry authentication?

Yes, most container registries support using personal access tokens or robot accounts in place of traditional passwords. When using the OpenSandbox API, pass the token as the password field in the image.auth object, with the corresponding username (often the token name or _token). The Docker runtime in server/src/services/docker.py passes these values directly to the registry without distinction between passwords and tokens.

Where are the registry credentials stored after I submit them?

Registry credentials are not persistently stored by the OpenSandbox server. According to the implementation in server/src/services/docker.py, the _resolve_image_auth() method extracts credentials from the incoming request and immediately passes them to the Docker daemon via the auth_config parameter in docker_client.images.pull(). The credentials exist only in memory during the request lifecycle and are not written to disk or retained in the sandbox state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}