> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Private registries

> Pull private base images from username/password registries, GCP Artifact Registry, or AWS ECR.

Private registry credentials apply to private image pulls during a template
build. The SDK helpers below set `base_image_auth`, which is request-time only:
the API stores the auth kind for retry decisions, not the credential value.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  builder = Template.from_image(
      "registry.example.com/team/app:1.0",
      username="robot",
      password="token",
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build \
    --from-image registry.example.com/team/app:1.0 \
    --registry-username robot \
    --registry-password token \
    --name demo
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # base_image_auth with kind=basic carries request-time username/password.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "demo",
      "base_image": "registry.example.com/team/app:1.0",
      "base_image_auth": {"kind": "basic", "username": "robot", "password": "token"}
    }'
  ```
</CodeGroup>

You can also attach credentials after selecting an explicit image:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
builder = (
    Template()
    .from_image("registry.example.com/team/app:1.0")
    .set_base_image_auth(username="robot", password="token")
)
```

<Note>
  The TypeScript SDK does not expose private registry auth yet; use the Python
  SDK, CLI, or HTTP API for authenticated base-image pulls.
</Note>

## GCP Artifact Registry

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  builder = Template.from_gcp_registry(
      "us-docker.pkg.dev/project/repo/app:latest",
      service_account_json="./service-account.json",
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build \
    --from-image us-docker.pkg.dev/project/repo/app:latest \
    --gcp-service-account-json @./service-account.json \
    --name demo
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # base_image_auth with kind=gcp_artifact_registry carries the parsed
  # service-account key JSON.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "demo",
      "base_image": "us-docker.pkg.dev/project/repo/app:latest",
      "base_image_auth": {
        "kind": "gcp_artifact_registry",
        "service_account_json": {"type": "service_account", "project_id": "project"}
      }
    }'
  ```
</CodeGroup>

## AWS ECR

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  builder = Template.from_aws_registry(
      "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
      access_key_id="AKIA...",
      secret_access_key="...",
      region="us-east-1",
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace template build \
    --from-image 123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest \
    --aws-access-key-id AKIA... \
    --aws-secret-access-key ... \
    --aws-region us-east-1 \
    --name demo
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # base_image_auth with kind=aws_ecr carries request-time AWS credentials.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "demo",
      "base_image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
      "base_image_auth": {
        "kind": "aws_ecr",
        "access_key_id": "AKIA...",
        "secret_access_key": "...",
        "region": "us-east-1"
      }
    }'
  ```
</CodeGroup>

Do not hard-code credentials in source files. Load them from a secret manager or
environment variables in CI.

## BuildKit Dockerfiles

For BuildKit Dockerfile builds that pull from more than one private registry,
the HTTP API also accepts `registry_auth`, a list of `{ registry, auth }`
entries. Each registry must match a Dockerfile `FROM` host. These credentials
are written to a temporary Docker config on the build worker and are removed
with the build staging directory.

Retries of private-registry builds require fresh `base_image_auth` or
`registry_auth` in the retry request; old request-time values are not replayed.

Builds with `internet_access=False` cannot pull from private registries unless
the required content is already available from an accessible BuildKit cache or
local build context. Keep build internet access enabled for private registry
pulls that must contact the registry.

## Related

* [Base image](./base-images)
* [Build](./build)