Introduction

You can use a container image from a private registry as the base image for a Cosmos cloud environment. Store a registry credential in Cosmos, then select it when creating the environment. Cosmos uses the credential to authenticate and pull the image during the build; it is not automatically installed as an environment variable inside your session. This guide covers two ways to authenticate to AWS ECR (Elastic Container Registry):

Static IAM credentials: an AWS access key ID and secret.
OIDC (recommended): credentials for your identity provider that Cosmos exchanges for temporary AWS credentials through an IAM role. This avoids storing long-lived AWS IAM access keys, but still requires an identity-provider client secret

Cosmos plans to eventually add support for private key for the OIDC client - stay tuned.

Before you begin

Have an image in a private ECR repository, with the dependencies required by Cosmos, including bash and git.
Copy the full image URI from ECR, including an existing tag, for example 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-environment:24.04. Replace the example account, region, repository, and tag with your own values. Do not assume your repository has a latest tag.
Have permission to configure IAM and ECR, create a registry credential in Cosmos, and create a cloud environment.
Use the same AWS region in the registry credential and the image URI.
If using OIDC authentication, have permission to configure an OIDC-compliant identity provider. This guide uses Okta as an example, with a custom authorization server and a machine-to-machine (M2M) OIDC client using the client credentials grant type.

The OIDC sign-in option must be enabled for your organization. If IAM role (OIDC client credentials) is not shown, contact your Augment Solutions Architect. This guide uses cloud environments; ECR support for self-hosted k8s environments depends on your organization’s configuration.

Import from AWS ECR using static IAM credentials

1. Grant read-only access to the repository

Create a dedicated IAM user for image pulls, or use an existing identity approved by your AWS administrator. Attach an IAM permissions policy with the following access, replacing the repository ARN with your own:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchCheckLayerAvailability"
      ],
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-environment"
    }
  ]
}

ecr:GetAuthorizationToken requires Resource: "*". Restrict the image and layer permissions to the repositories you need; push or administrator permissions are not required. For a cross-account repository, its repository policy must also allow the IAM identity to pull images. See AWS ECR repository policies. Create an access key for this IAM user and store it securely. Use the AWS access key pair, not a Docker username/password or a manually generated ECR login token.

2. Save the registry credential in Cosmos

Open cosmos.augmentcode.com → Settings → Registry Credentials, then select Add a credential.

Field	Value
Name	A descriptive name, such as `ecr-image-pull`. Use letters, numbers, underscores, or hyphens.
Registry type	AWS ECR
Sign-in method, if shown	Access keys
Access key ID	Your IAM user’s access key ID.
Secret access key	The matching secret access key, entered directly in the secure form.
Region	The region containing your ECR image, such as `us-east-1`.

Choose the available personal or shared access and Space settings so the intended environment creator can use the credential, then select Create credential.

Saving a registry credential stores its configuration. It does not contact ECR or try to fetch latest (or any other tag), and does not prove that the credential can pull an image.

Keep the key valid for future image builds, and rotate it according to your organization’s policy. Continue to Create the environment from the private image.

Import from AWS ECR using OIDC (recommended)

With this method, Cosmos:

Requests an OAuth access token from your identity provider using the client_credentials grant.
Passes that access token to AWS STS AssumeRoleWithWebIdentity to obtain temporary IAM role credentials.
Uses those credentials to request an ECR authorization token and pull the image.

Cosmos uses the token response’s access_token, not an id_token. Your identity provider must issue a signed JWT access token that AWS STS accepts for web-identity federation. An opaque access token is not sufficient. This guide uses Okta as an example of identity provider.

1. Configure your identity provider (Okta)

Configure three separate objects in Okta: an API Services application (the machine-to-machine client), a custom authorization server (the token issuer), and an access policy with a rule that allows this client to request tokens. Creating the application alone does not authorize it to use the server.

Your Okta organization must support custom authorization servers and the Client Credentials grant. API Access Management is required for custom authorization servers in production, and Client Credentials availability can depend on your Okta subscription. If the options below are missing, ask your Okta administrator to confirm availability. See Okta’s authorization-server guide and access-policy requirements.

1.1. Create the machine-to-machine application

Sign in to your organization’s Okta Admin Console and open the Applications page.
Select Create App Integration. If the new integration wizard does not offer API Services, select Classic experience, as described in Okta’s Client Credentials setup guide.
Choose API Services as the sign-in method, then select Next. Do not choose a browser-based web or single-page application: this flow has no interactive user sign-in or redirect URI.
Enter an application name, such as Cosmos M2M - AWS ECR, then select Save.
On the application’s General tab, locate Client Credentials. Record the Client ID and store the Client secret securely for entry into Cosmos later. If grant types are editable, ensure Client Credentials is enabled.
Use Client secret authentication with the token-endpoint method client_secret_basic. Cosmos sends the client ID and secret in an HTTP Basic header, not in the request body. Do not configure this application to require a private-key JWT instead. See Okta’s client authentication methods.

You M2M app should look like this:

You do not need to assign end users or grant Okta management API scopes for this image-pull flow. The next steps authorize this application against your custom server.

1.2. Create a custom authorization server

In the Okta Admin Console, open Security → API → Authorization Servers.
Select Add Authorization Server.
Enter a Name, such as Cosmos AWS ECR, and a Description explaining that the server issues tokens for private ECR image pulls.
Set Audience to aws-ecr for this guide’s example. This is the audience issued in the access token; keep it consistent with the AWS OIDC provider and IAM trust policy configured below. If your organization requires a different audience, replace the example consistently throughout the setup.
Select Save. On the server’s Settings tab, record its Issuer URL, including the /oauth2/<authorization-server-id> path.
Open the server’s Metadata URI, or its issuer URL followed by /.well-known/openid-configuration. Record the returned issuer and token_endpoint values. Use this exact HTTPS token endpoint in Cosmos; do not use a URL that redirects.

Use a custom authorization server, not the org authorization server at the bare Okta domain.

Your AuthZ server Settings tab should look like this:

1.3. Add the custom scope

On your custom authorization server, select Scopes → Add Scope.
Set Name to fetch-image. Enter a display phrase and description, such as Pull private ECR images.
Leave Require user consent for this scope unselected: client credentials requests have no user to provide consent.
Leave Set as a default scope unselected for this example; you will explicitly set fetch-image in Cosmos.
Select Create.

Do not request openid, profile, or other user-oriented OpenID scopes for this machine-to-machine flow. The custom scope lets Okta authorize token issuance; the IAM permissions policy, not this scope, grants access to ECR repositories. Your AuthZ server Scopes tab should look like this:

1.4. Create the access policy and rule

On the same authorization server, select Access Policies → Add Policy.
Enter a Name, such as Cosmos ECR client, and a description.
Under Assign to, choose The following clients and select the Cosmos M2M - AWS ECR application created above. Do not choose All clients for this dedicated policy.
Select Create Policy. Open the new policy and select Add Rule.

Enter a Rule Name, such as Allow client credentials, and configure:

Rule setting	Value
IF Grant type is	Client Credentials only. Expand Advanced if needed to find the option.
AND User is, if shown	No user. A rule that requires an assigned user does not match a client credentials request.
AND Scopes requested	Select the specific scope `fetch-image`, rather than allowing any scope.
Access token lifetime	A short lifetime approved by your organization, for example 1 hour.

Select Create Rule. Confirm that both the policy and its rule are active.
Review policy and rule order. Okta evaluates them in priority order and uses the first matching policy and rule.

Your AuthZ server Access Policies tab should look like:

The corresponding rule should look like:

1.5. Test the configuration with Token Preview

Use Okta’s Token Preview to check the application’s grant type, scope, and expected access-token claims before making a real token request.

On the same authorization server → Click on the Token Preview tab.

In Request Properties, configure:

Field	Value
OAuth/OIDC client	Select Cosmos M2M - AWS ECR. Type the application name to find it.
Grant type	Client Credentials.
Scopes	Select fetch-image.

Select Preview Token and inspect the Access Token result, not an ID token.
Confirm that the preview succeeds, iss matches your custom authorization server’s issuer, aud is aws-ecr, and scp includes fetch-image. Inspect sub and whether azp is present; verify their actual issued values in the next step before configuring AWS.

Your token preview should look like:

If the preview reports an error, check that the client and scope belong to this setup, the policy is assigned to Cosmos M2M - AWS ECR, and an active rule permits Client Credentials with fetch-image. Review policy and rule priority if the expected rule does not match.

1.6. Record the values and verify token issuance

The following are example values, not values to copy unchanged:

Setting	Example or source
Issuer URL	`https://example.okta.com/oauth2/authorization-server-id`; copy your server’s actual issuer.
Token URL	`https://example.okta.com/oauth2/authorization-server-id/v1/token`; copy `token_endpoint` from your server’s metadata.
Client ID and client secret	From the Client Credentials section on the API Services application’s General tab. Store the secret securely.
Authorization-server audience	`aws-ecr`, configured on the server.
Custom scope	`fetch-image`, configured on the server and allowed by the policy rule.

Before configuring AWS, run this curl request in a trusted local terminal. Replace the example URL with your authorization server’s token_endpoint and YOUR_CLIENT_ID with the client ID of Cosmos M2M - AWS ECR:

curl --request POST \
  --url 'https://example.okta.com/oauth2/authorization-server-id/v1/token' \
  --basic --user 'YOUR_CLIENT_ID' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=fetch-image'

When curl prompts for a password, enter the application’s client secret. You should get this response:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "XXXX.XXXX.XXXX",
  "scope": "fetch-image"
}

2. Register the issuer in AWS IAM

In the AWS console, open IAM → Identity providers → Add provider, then choose OpenID Connect.

Set Provider URL to the token’s exact iss value, including any authorization-server path. For the Okta example, use https://example.okta.com/oauth2/authorization-server-id, not just https://example.okta.com and not the /v1/token URL.
Set the AWS provider’s Audience to the token’s aud value. If the token includes azp, AWS uses that value instead for this check.
Create the provider in the same AWS account as the IAM role you will configure next.

Your identity provider should look like this:

3. Create the IAM role and trust policy

Create an IAM role, such as OktaECRPullRole. Attach the same repository-scoped ECR permissions policy shown in the static IAM credentials section. Separately, configure the role’s trust policy to allow sts:AssumeRoleWithWebIdentity from your IAM OIDC provider. Restrict it to the expected audience and application subject. For the example issuer above, a trust policy is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/example.okta.com/oauth2/authorization-server-id"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "example.okta.com/oauth2/authorization-server-id:aud": "aws-ecr",
          "example.okta.com/oauth2/authorization-server-id:sub": "EXPECTED_APPLICATION_SUBJECT"
        }
      }
    }
  ]
}

Replace the account ID, issuer host/path, audience, and subject with your own values. The provider ARN and condition-key prefixes include the issuer path but omit https://. This example assumes the token has no azp claim. If it has one, the :aud condition must match azp; AWS exposes the original aud as :oaud. Review AWS’s OIDC claim-to-condition mapping before adapting the policy. The trust policy controls who can assume the role; the attached permissions policy controls which ECR images the role can pull. Both are required.

4. Save the OIDC registry credential in Cosmos

Open cosmos.augmentcode.com → Settings → Registry Credentials → Add a credential and fill in:

Field	Value
Name	A descriptive name, such as `aws-ecr-oidc-pull`.
Registry type	AWS ECR
Sign-in method	IAM role (OIDC client credentials)
Role ARN	Your role ARN, for example `arn:aws:iam::123456789012:role/OktaECRPullRole`.
Token URL	Your identity provider’s HTTPS token endpoint, for example `https://example.okta.com/oauth2/authorization-server-id/v1/token`
Client ID	The machine-to-machine application’s client ID.
Client secret	The application’s secret.
Audience	Keep blank. Set only if your provider requires an `audience` parameter in the token request.
Scope	The scope your provider requires; for the example above, `fetch-image`.
Region	The region containing your ECR image, such as `us-east-1`.

Your Add registry credential view should look like:

Choose the appropriate access and Space settings, then select Create credential. Do not enter static AWS access keys for this method.

The Cosmos Audience field and the JWT audience are different settings. Cosmos only sends an audience request parameter when this field is filled in. Leaving it blank does not mean the token has no aud claim. For the Okta custom-authorization-server example, configure aws-ecr on the authorization server and leave the Cosmos field blank if no request parameter is required. AWS must still accept the audience actually issued in the token, accounting for azp when present.

Create the environment from the private image

After saving either a static IAM or OIDC registry credential, use these steps to create the environment:

Open cosmos.augmentcode.com → Settings → Environments.
Select Create an environment → Augment Cloud.
Enter an environment name.
Under Base image, select Private registry.
In Registry URL, enter the complete ECR image URI, including its existing tag. Do not add https://.
In Registry credential, select the static IAM or OIDC credential you created.
Select Create Environment and wait for the build to finish successfully before starting a session.

Your Create Environment view should look like:

The environment will build:

You should see this when created:

The build is the check that Cosmos can authenticate, retrieve the selected image, and prepare the environment. A successful standalone IdP → STS → ECR test confirms authentication and image access, but does not verify a Cosmos environment build or that the image contains the required tools. Congrats, you’ve configured a cloud environment pulling a custom image from ECR! 🎉

Troubleshooting

Symptom	What to check
OIDC sign-in method is missing	The option must be enabled for your Augment tenant. Contact your Augment Solutions Architect.
Token request fails	Confirm the client ID/secret, HTTP Basic authentication, allowed client-credentials grant, scope, and any provider-required audience parameter. Use the final publicly reachable HTTPS token URL; redirects and private-network endpoints are not supported.
AWS reports no matching OIDC provider or an invalid token/audience	Match the complete issuer URL, including its path. Check AWS access to discovery/signing keys and the provider’s accepted audience; account for `azp`.
STS returns access denied	Check the role ARN and trust policy’s provider, `sts:AssumeRoleWithWebIdentity` action, and exact audience/subject conditions. Do not substitute unsupported custom claims such as `scp`.
ECR denies authentication or image access	Check `ecr:GetAuthorizationToken`, repository-scoped pull permissions, region, and any cross-account repository policy.
Pull returns `MANIFEST_UNKNOWN` or image/tag not found	Confirm the repository and explicit tag exist. Successful authentication does not create a missing `latest` tag.

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Import images from private registry

Introduction

Before you begin

Import from AWS ECR using static IAM credentials

1. Grant read-only access to the repository

2. Save the registry credential in Cosmos

Import from AWS ECR using OIDC (recommended)

1. Configure your identity provider (Okta)

1.1. Create the machine-to-machine application

1.2. Create a custom authorization server

1.3. Add the custom scope

1.4. Create the access policy and rule

1.5. Test the configuration with Token Preview

1.6. Record the values and verify token issuance

2. Register the issuer in AWS IAM

3. Create the IAM role and trust policy

4. Save the OIDC registry credential in Cosmos

Create the environment from the private image

Troubleshooting

​Introduction

​Before you begin

​Import from AWS ECR using static IAM credentials

​1. Grant read-only access to the repository

​2. Save the registry credential in Cosmos

​Import from AWS ECR using OIDC (recommended)

​1. Configure your identity provider (Okta)

​1.1. Create the machine-to-machine application

​1.2. Create a custom authorization server

​1.3. Add the custom scope

​1.4. Create the access policy and rule

​1.5. Test the configuration with Token Preview

​1.6. Record the values and verify token issuance

​2. Register the issuer in AWS IAM

​3. Create the IAM role and trust policy

​4. Save the OIDC registry credential in Cosmos

​Create the environment from the private image

​Troubleshooting

Introduction

Before you begin

Import from AWS ECR using static IAM credentials

1. Grant read-only access to the repository

2. Save the registry credential in Cosmos

Import from AWS ECR using OIDC (recommended)

1. Configure your identity provider (Okta)

1.1. Create the machine-to-machine application

1.2. Create a custom authorization server

1.3. Add the custom scope

1.4. Create the access policy and rule

1.5. Test the configuration with Token Preview

1.6. Record the values and verify token issuance

2. Register the issuer in AWS IAM

3. Create the IAM role and trust policy

4. Save the OIDC registry credential in Cosmos

Create the environment from the private image

Troubleshooting