Connect AWS

Use your company's AWS sign-in to let commands, coding agents, and applications on your devboxes access AWS. After signing in, you'll choose an AWS account and permission set for each project. boxes.dev will keep that access available through a managed AWS profile, without a separate login on every machine.

This integration uses AWS IAM Identity Center, the company sign-in behind your AWS access portal. A team admin needs to enable it before members can connect.

Enable AWS for the team

If you're a team admin:

1. In the desktop app, open a project's Integrations → AWS page and choose Set up AWS.
2. Enter your company's AWS access portal URL, such as https://example.awsapps.com/start, and its IAM Identity Center region, such as us-east-1. If you don't know these values, ask whoever administers AWS at your company.
3. Continue to the browser and finish your normal company sign-in.
4. Choose an assigned AWS account and permission set for the current project, then choose Use this access.

AWS will validate the portal and region before boxes.dev saves them for the team. Other members can then connect with their own company identities without entering those details.

Your current project will also be connected. Open a new terminal on one of its machines and check your AWS identity.

To change the team details later, use Team setup → Edit on the AWS page. Members' existing connections will keep their previous settings until they reconnect.

Connect your project

Once your team has enabled AWS:

1. In the desktop app, select your project and open Integrations → AWS.
2. Choose Connect AWS and finish company sign-in in your browser. Supported desktop versions will receive the result automatically. If that return does not work, choose Use a code instead and check that AWS shows the same code as boxes.dev. Browser, mobile, and older desktop clients use this code path.
3. Return to boxes.dev and choose one of the AWS accounts your company has assigned to you, then one of its permission sets. Choose Use this access to save the account and permissions that commands will use through the project's default boxes-dev profile.

Choose AWS access for the project and the credentials its machines should receive. Select the image to enlarge it.

Check your AWS identity

Open a new terminal on the project's Template box or a devbox and run:

aws sts get-caller-identity

Check that the command's returned account and identity match the access you selected. New terminals will use AWS_PROFILE=boxes-dev. Existing Codex and Claude sessions will finish their current work and pick up AWS before their next turn. Already-open shells keep their original environment, so open a new terminal after connecting or changing profiles.

Another project can reuse your saved sign-in and select different assigned access. No Template box snapshot or repository change is required.

Add another profile

Use named profiles when one project needs access to more than one AWS account or permission set.

1. In Integrations → AWS → Managed profiles, choose Add profile.
2. Choose a lowercase name beginning with boxes-, such as boxes-staging, and select its AWS account and permission set.
3. Choose Add profile to save it.
4. Select the profile explicitly in commands that need it:

aws sts get-caller-identity --profile boxes-staging

A project supports up to ten managed profiles, including boxes-dev. Profile names cannot change after creation. Use Edit to change the default profile's access, or a named profile's menu to edit or remove it. Removing the default means removing AWS from the project.

Reconnect or remove access

If your company sign-in expires, choose Reconnect AWS in the warning or Reconnect on the AWS page. In a terminal, aws sts get-caller-identity --profile boxes-dev will also explain when AWS needs to be reconnected. Your existing profile selections will be kept. On mobile, choose Open AWS sign-in from the code-confirmation step, finish sign-in in your phone's browser, and return to boxes.dev.

Dismissing an expiration warning will not reconnect AWS. Your company's session policies determine when you'll need to sign in again.

The AWS options menu offers two removal actions:

• Remove from this project will stop new managed credentials for this project while leaving other projects connected.
• Sign out of AWS everywhere will disconnect every boxes.dev project using your saved sign-in.

Neither action changes your company's AWS assignments, signs you out of other browser sessions, or revokes temporary credentials AWS already issued. Those credentials remain valid until their AWS expiration. For immediate revocation, use your company's AWS administration controls; if you don't have that access, ask your AWS administrator.

Check credential precedence

The boxes-dev profile is a default. If a command uses an unexpected AWS identity, check for an explicit --profile, a different AWS_PROFILE, access-key environment variables, or credentials selected in application code. These can override the default under AWS's normal rules. For Codex, choose another profile on the command itself or in Codex configuration; an AWS_PROFILE assignment in a shell startup file such as .bashrc may be overridden.

The managed profile works with the AWS CLI and applications that use standard AWS configuration on the machine. It uses AWS's credential_process mechanism to obtain temporary credentials when a tool needs them. Your renewable company sign-in stays encrypted in boxes.dev; it is not copied into devboxes or snapshots, and the temporary credentials are not written to the AWS credentials file.

Profiles you create yourself or import from your computer remain your responsibility, including separate admin profiles; boxes.dev does not refresh them. To use an existing personal profile for a Codex command, select it explicitly:

AWS_PROFILE=personal aws sts get-caller-identity

If a user-owned profile has the same name as a managed profile, rename or remove the user-owned section in ~/.aws/config on the affected machine, then choose Try again on the AWS page. boxes.dev will preserve unrelated profiles and settings.

Containers and supported accounts

Containers do not automatically receive the host machine's AWS configuration or access to its credential helper. Configure AWS access inside containers separately; do not copy the central company sign-in into them.

Each boxes.dev team supports one IAM Identity Center organization, and each member uses one personal sign-in to that organization. Managed profiles can select only the accounts and permission sets assigned to that identity.