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

> Learn to configure authentication for private container registries in OpenSandbox sandboxes. Securely access your images using username and password with the Docker runtime in this guide.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.

```json
{
  "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.

```bash
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`](https://github.com/alibaba/OpenSandbox/blob/main/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:

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

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/api/schema.py)** | Defines `ImageAuth`, `ImageSpec`, and `CreateSandboxRequest` (the request model) |
| **[`server/src/services/docker.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/docker.py)** | Resolves authentication via `_resolve_image_auth()`, pulls images with `auth_config` |
| **[`server/src/services/k8s/kubernetes_service.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/kubernetes_service.py)** | Contains `_ensure_image_auth_support()` which rejects auth for Kubernetes runtime |
| **[`specs/sandbox-lifecycle.yml`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/docker.py) (`_resolve_image_auth()` and `_pull_image()`), while the API schema is defined in [`server/src/api/schema.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.