Connect your AWS account

Updated November 2, 2026 · Plans: Free, Pro, Enterprise

Overview

Connecting an AWS account lets ArchFoundry read what already runs there, draw it, show what AWS actually billed instead of a projection, and deploy what you design. You pick what ArchFoundry may do, then create one CloudFormation stack in AWS from a link that has everything filled in, and click the link AWS shows you when it is done. You copy and paste nothing. ArchFoundry never takes access keys, and stores no credential.

The stack makes IAM roles (identities in your account that ArchFoundry may use): a read-only one, and, unless you choose Can look, cannot change anything, a second one that can create, change and remove what you deploy.

Prerequisites

• An owner or admin role in your ArchFoundry organization. Members can see connected accounts but cannot add, draw, name or remove them.
• An AWS account, and permission in it to create IAM roles with CloudFormation.
• No AWS account yet? On the connect screen, open No AWS account yet? and click Create one. AWS asks for a card and a phone number, and it takes about 10 minutes. Then come back to ArchFoundry.
• Optional: GitHub connected first (Connect GitHub, under Settings or on this screen). Then the stack also lets GitHub Actions in that organization push images and publish sites, so ArchFoundry can build on push. Deploying works without it.

Steps

1. In the workspace sidebar, click Cloud accounts, then Connect an account. On the canvas, the Connect AWS button opens the same screen.
2. Pick what ArchFoundry can do. Can also create, change and remove what you deploy is already picked; pick Can look, cannot change anything for read-only. With deploying picked and GitHub connected, the screen names the GitHub organization whose GitHub Actions can push to your account.
3. Click Connect in AWS →. The AWS console opens in a new tab with everything filled in. AWS uses the account you are signed in to; its name is at the top right of AWS. Who gets access names your ArchFoundry organization and who made the link. If you do not know that organization, do not create the stack.
4. In AWS, tick the box at the bottom that starts "I acknowledge that AWS CloudFormation might create IAM resources", then press Create stack.
5. Wait a minute or two, until AWS says the stack is complete. Then open the stack's Outputs tab and click the link that starts https://app.archfoundry.ai.
6. ArchFoundry opens, checks the roles with AWS, and connects the account by itself. It shows Connected and prod, AWS account followed by your account number.
7. Optionally, open Change name or region, or remove, change the Name for this account or the Region your app runs in, and press Save.
8. Click See what's running to draw what runs in the account on a new diagram.

In regions where the stack can tell ArchFoundry, the connect screen says This page turns to Connected by itself. Go back to the ArchFoundry tab and wait. It usually takes 1 to 3 minutes. You do not need steps 5 and 6.

If the link is more than 7 days old, the page asks first: check the account number and click Connect. A link someone else made works only for them.

The stack is created in US East (N. Virginia). To use another region, press Change beside Connect in AWS before step 3.

To name the account prod, staging or dev for your team, press Name environment on its row in the connect screen. The name shows wherever the account appears, and a deploy to it asks you to type that word to confirm.

When a stack connects an account

When a stack connects an account, every other owner and admin of your organization sees a notice on Cloud accounts: who connected which AWS account, under which name, and what ArchFoundry can do there. Keep hides the notice for everyone. Remove removes the connection, so ArchFoundry stops using it; to end access in AWS too, delete the stack there. The connection is also listed on Activity.

Example

The link in the stack's Outputs has this shape. You click it; you never copy it:

https://app.archfoundry.ai/home/accounts/finish#state=...&account=<your-account-id>&region=us-east-1&read=arcfoundry-readonly&deploy=arcfoundry-deploy

With Can look, cannot change anything, the link has no deploy= part.

ArchFoundry checks the values itself before it connects anything.

Expected result: the page shows Connected and prod, AWS account 123456789012. (with your own account number), and the account appears under Cloud accounts with the status Connected.

Verify it worked

• Under Cloud accounts, the account shows Connected and the regions you chose.
• With deploying picked, the account's row says deploy granted.
• On the connect screen, Details then Every permission it has lists every action the read-only role is granted, and the ones deliberately absent. It can describe and list your infrastructure and read two Cost Explorer reports. It cannot read an object, a secret, a parameter or a table row, and it cannot create, change or delete anything.
• We read your account only when you ask.

Troubleshooting

AWS shows ROLLBACK_COMPLETE. The stack could not finish. Open the stack's Events tab in AWS and look for a reason that says already exists. If one names token.actions.githubusercontent.com or arcfoundry-readonly, press the button with those words on the connect screen. If one names arcfoundry-boundary, arcfoundry-ecs-execution, arcfoundry-image-push or arcfoundry-deploy, an earlier deploy stack is still in this account: delete it in AWS, then press Back and Connect in AWS. If AWS cannot delete it, email support@archfoundry.ai. Otherwise, press Try again. Each makes the same stack under a new name, with the change that fixes it, and it uses the Outputs link. You do not need to delete the failed stack; it owns nothing and costs nothing. If AWS still says CREATE_IN_PROGRESS or ROLLBACK_IN_PROGRESS, wait: it can take up to 10 minutes.

AWS says you are not authorized. The AWS sign-in you used cannot create IAM roles. Sign in to AWS as the account's owner or an administrator, then press Try again.

ArchFoundry has not heard from the stack. The connect screen waits 15 minutes, and 15 more each time you come back to its tab. If AWS shows CREATE_COMPLETE, open the stack's Outputs tab and click the link. If it shows ROLLBACK_COMPLETE, see AWS shows ROLLBACK_COMPLETE above.

ArchFoundry needs you to confirm AWS account ... The stack finished more than an hour after you pressed Connect in AWS, or many accounts were connected in the last hour. Check the account number and press Connect.

AWS's page named a different organization or person. Who gets access on AWS's page did not name your organization and you as they are today, so nothing was connected, and that stack can never connect. Delete the stack in AWS, then connect again from Cloud accounts. Your organization's owners and admins see it on Cloud accounts and Activity.

Not connected yet. In the AWS tab, click Outputs, then the link. The connect screen did not hear back. Finish steps 4 and 5 above in the AWS tab. Open my stack in AWS on the connect screen takes you to the stack.

Sign in to finish connecting. You are not signed in in this browser. Sign in, and you come back to the same page with your account number.

AWS would not let ArchFoundry use the role yet. The stack may still be creating. Wait a minute and press Check again.

We could not confirm the role is read-only. AWS did not answer clearly. Press Check again in a moment.

Not your link. Each link works only for the person who pressed Connect in AWS. Ask them to open it.

This link was made in another organization. Nothing was connected. If that organization is yours too, sign out, sign in to it, and open the link again. If it is not, press Block that organization: once AWS confirms the stack is that organization's, it can no longer connect this AWS account. Then delete the stack in AWS.

This link expired after 7 days. Delete the stack in AWS, then press Connect an account in Cloud accounts again.

The stack fails, or you use Terraform. Open Details, then Connect another way. Create the role with the Terraform module, or fix the stack, then paste the role's ARN (its full name, starting arn:aws:iam::) into Role ARN and click Connect.

That looks like an AWS access key. We never accept keys. You pasted a key instead of a role ARN under Connect another way. Create the read-only role and paste its ARN.

Only an owner or admin can connect an account. Ask an owner or admin of your organization to connect the account, or to make you an admin.

The account shows Failing, with a message from AWS. The role is missing, or no longer trusts ArchFoundry. Check that the CloudFormation stack still exists in your account, then connect again.

Connecting is not enabled on this server yet. You reached a server without account connections switched on. Make sure you are on app.archfoundry.ai.

Read-only for now. The deploy role failed a check. The account is connected and ArchFoundry can see what runs there. The deploy role was not ready or not usable. Wait a minute and press Check again. If you already had a deploy role, ArchFoundry keeps it.

What the deploy and plan roles can never do. Both templates deny three things outright, so AWS refuses them even if another permission would allow them: deleting a database snapshot or a saved backup, reading a database password that RDS (Amazon's managed database service) keeps for you, and changing the role's own permissions or the ArchFoundry stacks in your account. The template's description says so: "Archie can never delete a snapshot or a saved backup, read a database password or change these permissions. This template denies them." A stack created from an older template does not have these limits until you update it with the current template.

The stack fails because AWS already trusts GitHub in this account, or a role named arcfoundry-readonly already exists. See AWS shows ROLLBACK_COMPLETE above: press the button for your case on the connect screen.

ArchFoundry could not use the read-only role in this account. The stack was made without the read-only role and the existing one is not usable. Press Show the steps: delete the arcfoundry-readonly stack in AWS, connect again with Can look, cannot change anything, then on its row press Read-only · grant deploy and paste RoleArn from the Outputs of the stack whose link brought you there.

Letting ArchFoundry deploy on an account connected read-only. The read-only role never changes. On the connected account click Read-only · grant deploy, run the deploy template, paste the new role's ARN under Deploy role ARN, and click Grant deploy. Details, then Read the templates, links each template so you can read it first.

A deploy stops with AccessDenied on a new kind of resource. The deploy template grows as ArchFoundry does. In CloudFormation, select the stack whose name starts with arcfoundry-deploy and press Update. Choose Replace existing template, then Amazon S3 URL, and paste https://arcfoundry-templates-828311628425.s3.us-east-1.amazonaws.com/connect/arcfoundry-deploy.yaml. Finish the update, then plan again.

Removing access. To stop access, delete the stack you made in AWS: arcfoundry-deploy if you picked deploying (it holds both roles), or arcfoundry-readonly. Remove here only stops ArchFoundry using it.

Next steps

• Draw and manage what already runs in AWS
• Deploy a diagram to your AWS account
• Connect Claude, which needs a connected account.