Connect AWS

Let commands, coding agents, and applications on your devboxes use AWS. Each project gets a managed AWS profile named boxes-dev, and boxes.dev will keep its credentials available on every devbox without a separate login on each machine.

You can give the profile access in one of two ways:

• Company SSO uses your company's AWS access portal, which runs on AWS IAM Identity Center. You'll sign in with your company identity, then choose an assigned AWS account and permission set. A team admin needs to set it up once for the team.
• Access keys use a long-term access key that belongs to an IAM user. No team setup is needed, so use this if your company doesn't sign in to AWS through an access portal.

Enable Company SSO for the team

If you're a team admin:

1. In the desktop app, open a project's Integrations → AWS page. Next to Sign in with, choose Company SSO, then choose Set up Company SSO.
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. You can paste the portal address straight from your browser. If you don't know these values, ask whoever administers AWS at your company, or find them in your AWS access portal: choose Access keys next to any permission set, then copy the SSO Start URL and SSO Region under AWS IAM Identity Center credentials.
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 terminal on one of its machines and check your AWS identity.

To change the team details later, open Company SSO details on the AWS page and choose Edit team setup. Members' existing connections will keep their previous settings until they reconnect.

Connect with Company SSO

Once your team has enabled Company SSO:

1. In the desktop app, select your project and open Integrations → AWS. Company SSO will already be selected next to Sign in with.
2. Choose Connect Company SSO 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.

If the list is empty or is missing access you expect, ask your AWS administrator to assign it to your company identity, then choose Refresh. You won't need to sign in again.

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

Another project can reuse your saved sign-in and select different assigned access.

Use an access key

An access key gives the profile the permissions of one IAM user in one AWS account. Create a key for an IAM user whose permissions cover only what this project needs, because agents and anyone else who can run commands on the project's devboxes will be able to read it. AWS explains how to create an access key.

1. In the desktop app, select your project and open Integrations → AWS.
2. Next to Sign in with, choose Access keys. It's already selected if your team hasn't set up Company SSO.
3. Enter the access key ID and secret access key, then choose Use this key.

boxes.dev will check the key with AWS before saving it. Temporary keys, whose IDs begin with ASIA, and keys for the account's root user won't be accepted. After saving, the profile shows the IAM user's name, the account ID, and the last four characters of the access key ID.

The key is stored encrypted in boxes.dev and is used only for this project. It isn't written to files on your devboxes; AWS tools receive it from boxes.dev when they need credentials and keep it in memory, which a sleeping devbox or a snapshot can retain. Unlike Company SSO credentials, an access key doesn't expire, so you'll never need to reconnect it.

Check your AWS identity

Open a 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 chose. Terminals will use AWS_PROFILE=boxes-dev, and ones that are already open will pick up a change at their next prompt. In a terminal that was waiting for a command, press Enter once before running aws. Existing Codex and Claude sessions will finish their current work and pick up AWS before their next turn. Programs that are already running keep their original settings until they restart.

No Template box snapshot or repository change is required. If the AWS page still shows Applying AWS access to your devboxes, devboxes that are asleep will get access when they next start, and devboxes that need a boxes.dev update will get it after updating.

Add another profile

You can also ask an agent to add or change a Company SSO profile. It can list the accounts and permission sets assigned to your sign-in, including their names and account IDs. Before saving, it will ask you to approve the specific project, profile, account and permission set. That access will be available to programs and agents on all of the project's boxes. The agent has ten minutes to apply the approved change; the saved choice will remain afterward.

The agent cannot replace a profile that holds an access key or remove a profile through this setup command. Use the AWS page for those changes and for signing in.

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

1. In Integrations → AWS → Managed profiles, choose Add profile.
2. Choose a lowercase name beginning with boxes-, such as boxes-staging.
3. Choose Company SSO and select an AWS account and permission set, or choose Access keys and enter a key.
4. Choose Add profile to save it.
5. 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 SSO 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. Access-key profiles keep working while Company SSO needs reconnecting, and you can still edit any profile, for example to switch it to an access key.

To replace an access key, edit its profile and enter the new key. New AWS commands will use the new key once it reaches your devboxes, but a long-running program that already loaded the old key will keep using it until it restarts. The old key stays active in AWS, so deactivate it in the AWS console once nothing needs it.

The AWS options menu offers two removal actions:

• Remove from this project will stop new managed credentials for this project, delete boxes.dev's copy of any access keys it uses, and leave other projects connected.
• Sign out of Company SSO will disconnect your Company SSO profiles in every boxes.dev project. Access-key profiles will stay. If boxes-dev used Company SSO, commands will need --profile to use the remaining profiles until you choose default access again.

Removing access in boxes.dev doesn't revoke anything in AWS. Temporary Company SSO credentials remain valid until their AWS expiration, and an access key stays active until you deactivate it in AWS. Programs that already received credentials can keep using them until then. Neither action changes your company's AWS assignments or signs you out of other browser sessions. 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.

AWS tools also prefer keys in ~/.aws/credentials over boxes.dev's managed access. If that file has a section with the same name as a managed profile, such as [boxes-dev], rename or remove the section on the affected machine.

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 give tools credentials when they need them. Your renewable company sign-in stays encrypted in boxes.dev and is not copied into devboxes or snapshots. Access keys are also stored encrypted, and boxes.dev doesn't write any credentials to the AWS credentials file.

Personal profiles with names outside boxes-* 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

Profile names starting with boxes- are reserved for boxes.dev. If an edit to ~/.aws/config changes one of those profiles or removes its ownership comments, boxes.dev will restore it from the project's AWS settings during the next sync or agent start. Removed managed profiles will also be cleaned up. Make changes to managed access on the AWS page; use a different name for a personal profile or alias, such as personal or oro-staging. Other profiles, comments, and settings are preserved.

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. Company SSO profiles can select only the accounts and permission sets assigned to that identity. Each access-key profile uses one IAM user's key in that user's AWS account.