# How to Configure Registry Authentication and Manage Multiple Registry Credentials in Apple Container

> Learn to configure registry authentication and manage multiple registry credentials in Apple Container. Securely store and access credentials using macOS Keychain for seamless container registry management.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-13

---

**Apple Container stores default registry settings in a [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file and securely manages multiple credentials using the macOS Keychain, enabling seamless authentication across different container registries without exposing sensitive data.**

The `apple/container` project provides a robust authentication system that separates configuration from credentials. Developers can configure registry authentication for various environments while the system handles credential storage securely through native macOS APIs.

## Configure Default Registry Settings

Apple Container uses a TOML configuration file to define default registry behavior. The system parses these settings through [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift).

### Understanding the config.toml Structure

The `[registry]` table in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) defines the default domain assumed when an image reference lacks an explicit registry host. By default, this value is `"docker.io"`:

```toml
[registry]
domain = "docker.io"

```

### Setting a Custom Default Domain

To change the default registry for all commands, modify the `domain` key in your configuration file:

```bash
cat >> ~/.config/container/config.toml <<EOF
[registry]
domain = "my-registry.example.com"
EOF

```

This setting applies globally, allowing you to use shorthand image names without specifying the registry host each time.

## Authenticate with Container Registries

The `container registry login` command handles authentication with container registries, storing credentials securely in the macOS Keychain rather than plaintext files.

### Interactive Login

To authenticate interactively, run the login command with the server hostname:

```bash
container registry login my-registry.example.com

```

The CLI prompts for username and password, then stores the credentials in the Keychain via [`RegistryResource.swift`](https://github.com/apple/container/blob/main/RegistryResource.swift).

### Non-Interactive Login for CI/CD

For automated pipelines, pass credentials via flags to avoid interactive prompts:

```bash
echo "$REGISTRY_TOKEN" | container registry login \
    --username "$REGISTRY_USER" \
    --password-stdin \
    my-registry.example.com

```

This approach stores the credentials securely without exposing them in shell history or process lists.

### Connection Scheme Configuration

The `--scheme` flag controls whether the client uses HTTP or HTTPS. The default value `auto` intelligently selects the protocol based on the registry address:

- **Internal registries**: Loopback addresses, RFC1918 private networks, or the host's default DNS domain use HTTP
- **External registries**: All other addresses use HTTPS

```bash
container push \
    --scheme http \
    my-internal-registry.local/myrepo/app:latest

```

Explicitly set `--scheme https` to force encrypted connections, or `--scheme http` for insecure internal testing.

## Manage Multiple Registry Credentials

Apple Container supports unlimited registry credentials simultaneously, automatically selecting the appropriate set based on the image reference hostname.

### Storing Credentials per Registry

Each call to `container registry login` creates a separate Keychain entry keyed by the server name. The system stores credentials for `docker.io`, `my-registry.example.com`, and `ghcr.io` concurrently without conflicts:

```bash
container registry login docker.io
container registry login ghcr.io
container registry login my-registry.example.com

```

When you reference an image, the CLI retrieves the matching credentials automatically based on the registry host in the image path.

### Listing Stored Credentials

The `container registry list` command displays hostnames with stored credentials without exposing secret values:

```bash

# Human-readable output

container registry list

# Quiet mode - hostnames only

container registry list -q

# Machine-readable JSON

container registry list --format json

```

### Removing Registry Credentials

To revoke authentication for a specific registry, use the logout command:

```bash
container registry logout my-registry.example.com

```

This removes the associated Keychain entry entirely, requiring re-authentication on subsequent access attempts.

## Implementation Details

The authentication system relies on two primary components in the codebase:

**Configuration Parsing**: [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift) parses the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file and exposes the default registry configuration to the rest of the application.

**Credential Management**: [`Sources/ContainerPersistence/RegistryResource.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/RegistryResource.swift) handles all Keychain interactions, implementing secure storage and retrieval of username-password pairs keyed by registry hostname.

The test suite in [`Tests/ContainerResourceTests/RegistryResourceTests.swift`](https://github.com/apple/container/blob/main/Tests/ContainerResourceTests/RegistryResourceTests.swift) validates hostname parsing and credential selection logic, ensuring reliable matching between image references and stored credentials.

## Summary

- **Default registry**: Configure the `[registry]` table in [`config.toml`](https://github.com/apple/container/blob/main/config.toml) to set a custom domain for shorthand image references
- **Secure storage**: Credentials are encrypted in the macOS Keychain via [`RegistryResource.swift`](https://github.com/apple/container/blob/main/RegistryResource.swift), never stored in configuration files
- **Multiple registries**: Store unlimited credentials keyed by hostname; the system automatically selects the correct set based on the image reference
- **Connection control**: Use `--scheme auto` for intelligent HTTP/HTTPS selection, or override with explicit `http` or `https` values
- **Credential lifecycle**: Use `container registry login` to add, `container registry list` to view, and `container registry logout` to remove authentication data

## Frequently Asked Questions

### Where does Apple Container store registry passwords?

Apple Container stores registry passwords in the macOS Keychain, not in the [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file or environment variables. The [`RegistryResource.swift`](https://github.com/apple/container/blob/main/RegistryResource.swift) module handles all credential storage and retrieval through native Security framework APIs, ensuring passwords remain encrypted and accessible only to the application.

### How do I switch between different registry credentials?

You do not need to manually switch credentials. Apple Container automatically selects the appropriate credential set based on the registry hostname extracted from the image reference. When you run `container pull ghcr.io/user/app`, the system retrieves the `ghcr.io` credentials; for `docker.io/library/nginx`, it uses the Docker Hub credentials.

### Can I use HTTP instead of HTTPS for internal registries?

Yes. Use the `--scheme http` flag when pushing or pulling images to force unencrypted connections. Alternatively, use `--scheme auto` (the default), which automatically detects internal addresses—including loopback interfaces, RFC1918 private networks, and the host's default DNS domain—and uses HTTP for these while maintaining HTTPS for external registries.

### How do I configure a default registry for all operations?

Set the `domain` key in the `[registry]` section of your [`config.toml`](https://github.com/apple/container/blob/main/config.toml) file. This value, parsed by [`ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/ContainerSystemConfig.swift), defines the assumed registry when an image reference does not contain an explicit host. Change this from the default `"docker.io"` to your private registry to enable shorthand image names across all commands.