Amazon Web Services

CloudThinker runs the AWS CLI against your account to answer questions about compute, storage, identity, cost, and monitoring. You connect with an IAM role that CloudThinker assumes for short-lived credentials (recommended), or with an IAM user’s access keys.

Prerequisites

An AWS account where you can create IAM roles (or IAM users, for the access-key method).
Access to AWS CloudShell in that account. The setup script runs there, so you install nothing.
For cost questions and Optimize: Cost Explorer turned on in the account (Billing and Cost Management → Cost Explorer → Launch Cost Explorer, in the management account for an organization). AWS can take up to 24 hours to activate it on a new account.
In an AWS Organization, check your service control policies (SCPs). An SCP that denies sts:AssumeRole from outside principals blocks the role, and one that denies regions hides those regions from agents. From the management account, list the SCPs on the account under AWS Organizations → AWS accounts → your account → Policies, or run aws organizations list-policies-for-target --target-id <account-id> --filter SERVICE_CONTROL_POLICY.
Opt-in regions, such as ap-east-1 or me-south-1, are invisible to agents until you enable them under Account → AWS Regions in the AWS console.

Setup

Open the connect dialog first: in the sidebar, click More → Workspace settings → Connections, select Amazon Web Services, and click Connect. Then follow the tab for the method you pick at the top of the dialog.

Role-Based (recommended)
Access Keys

The dialog generates an External ID (a unique identifier that ties your role to this CloudThinker workspace and prevents the confused-deputy problem; AWS doesn’t treat it as a secret) and builds a setup script around it.

Keep the dialog open until you click Connect. Closing it discards the External ID, and a new dialog generates a different one, so a role built from the old ID won’t match.

Name the account

Fill in Alias (for example production) and Description (for example Production AWS account, main workloads). Agents read the description to pick the right account. Default AWS region (optional) is only a starting point: agents can use any region the role can reach.

Open CloudShell

Click Open CloudShell and sign in to the AWS account you want to connect.

Run the setup script

To read the script first, click View script in the dialog. Then click Copy Script to Clipboard, paste it into CloudShell, and press Enter. The script:

Stops if a role named CloudThinkerAccessRole already exists.
Creates CloudThinkerAccessRole with a trust policy that only CloudThinker can assume, and only with your External ID.
Attaches the AWS managed ReadOnlyAccess policy.
Prints the role’s ARN.

The full script, for review before you run it

The dialog fills in your External ID and the CloudThinker principal. It also prints progress messages, left out here.

#!/bin/bash
set -e
ROLE_NAME="CloudThinkerAccessRole"

# Stop if the role already exists
if aws iam get-role --role-name "$ROLE_NAME" >/dev/null 2>&1; then
  echo "ERROR: Role '$ROLE_NAME' already exists!"
  exit 1
fi

# Trust policy: only the CloudThinker principal, only with your External ID
cat > trust-policy.json <<'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<CloudThinker principal shown in the dialog>" },
      "Action": "sts:AssumeRole",
      "Condition": { "StringEquals": { "sts:ExternalId": "<your External ID>" } }
    }
  ]
}
EOF

aws iam create-role --role-name "$ROLE_NAME" \
  --assume-role-policy-document file://trust-policy.json \
  --description "Role for CloudThinker to access AWS resources"

aws iam attach-role-policy --role-name "$ROLE_NAME" \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

rm -f trust-policy.json
aws iam get-role --role-name "$ROLE_NAME" --query 'Role.Arn' --output text

The end of the output looks like this:

==========================================
  ✅ Setup Complete!
==========================================

Copy this Role ARN and paste it in the connection form:

arn:aws:iam::123456789012:role/CloudThinkerAccessRole

Paste the Role ARN and connect

Paste the ARN into AWS Role ARN. Leave AWS External ID as it is: it’s filled in for you and must match the script. Click Connect.Success state: the status moves through Connecting and Verifying, and the account shows a Connected status. Discovery now runs once in the background and spends credits. Check the Discovery section on the detail panel before your first prompt. See What happens after you connect.

Set the environment

Open Amazon Web Services in More → Workspace settings → Connections, click the pencil icon on the account’s row, and set Environment in Edit Instance. It labels the account for people and agents. See Set the environment.

Ask a verification question

Open a chat and ask the verification question. The answer should name your real 12-digit account ID.

Prefer to create the role yourself, for example in Terraform or CloudFormation? Expand Manual steps in the dialog. It shows the trust policy with your External ID and the CloudThinker principal filled in. The principal is the same for every workspace. Only the External ID changes with each dialog. With manual steps you can use any role name, because CloudThinker uses the ARN you paste. The shape is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<CloudThinker principal shown in the dialog>" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "<your External ID>" }
      }
    }
  ]
}

The same role in Terraform, with both values passed in as variables:

variable "cloudthinker_principal" {}
variable "cloudthinker_external_id" {}

resource "aws_iam_role" "cloudthinker" {
  name = "CloudThinkerAccessRole"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { AWS = var.cloudthinker_principal }
      Action    = "sts:AssumeRole"
      Condition = { StringEquals = { "sts:ExternalId" = var.cloudthinker_external_id } }
    }]
  })
}

resource "aws_iam_role_policy_attachment" "read_only" {
  role       = aws_iam_role.cloudthinker.name
  policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}

output "role_arn" {
  value = aws_iam_role.cloudthinker.arn
}

Copy both values from an open dialog, and keep that dialog open until terraform apply finishes and you’ve pasted the role_arn output into AWS Role ARN.The dialog has no timer, but the External ID lives only in that open browser tab. Closing the dialog or reloading the page loses it, and there’s no way to bring an External ID back into a new dialog. That’s a limitation for pull-request-reviewed Terraform, where apply can run hours later in CI: keep the dialog open until the pipeline finishes, or start a fresh dialog and update the trust policy’s External ID before you click Connect.

Use this only when your organization doesn’t allow cross-account roles. Access keys are long-lived, so you have to rotate them yourself, for example every 90 days. See Rotate a credential.

Name the account

Select Access Keys at the top of the dialog. Fill in Alias, Description, and optionally Default AWS region (optional).

Run the setup script in CloudShell

Click Open CloudShell, then Copy Script to Clipboard, and run it in CloudShell. It creates an IAM user named CloudThinkerUser, attaches ReadOnlyAccess, creates an access key, and prints AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.AWS shows the secret only once, so keep CloudShell open until both values are in the dialog. The secret stays in the terminal output, so run clear and close the CloudShell session once you’ve connected.

Enter the keys and connect

Paste both values into the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY fields and click Connect.Success state: the account shows a Connected status. Discovery now runs once in the background and spends credits. Check the Discovery section on the detail panel before your first prompt. See What happens after you connect.

Set the environment

The user gets ReadOnlyAccess, so it can read S3 objects too. To switch it to the narrower set in Required permissions, run this in CloudShell:

USER=CloudThinkerUser
aws iam attach-user-policy --user-name $USER --policy-arn arn:aws:iam::aws:policy/job-function/ViewOnlyAccess
aws iam attach-user-policy --user-name $USER --policy-arn arn:aws:iam::aws:policy/SecurityAudit
aws iam put-user-policy --user-name $USER --policy-name CloudThinkerCostRead \
  --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"ce:Get*","Resource":"*"}]}'
aws iam detach-user-policy --user-name $USER --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

Connect more accounts

Each AWS account is its own connection. Click Connect again on Amazon Web Services, give the account its own alias, and run the script from that dialog in the new account’s CloudShell. Always copy the script from the dialog you’re completing, so the trust policy carries the External ID that dialog shows. Bulk onboarding isn’t supported yet. Each dialog generates its own External ID, so a StackSet or a single Terraform apply can’t create roles for several connections at once. Each account needs its own dialog and its own role. For many accounts, the fastest path is the Terraform module above, applied once per account with the values from that account’s open dialog. For costs across an AWS Organization, connect the management account. That gives Optimize organization-wide cost only. Agents see resources in a member account only through that account’s own connection.

Connection details

Field	Method	Description	Example
Alias	Both	Short name for this account. Blank picks one for you.	`production`
Description	Both	What the account is. Agents use it to choose between accounts.	`Production AWS account`
Default AWS region (optional)	Both	Starting region. Agents can use other regions the credential allows.	`us-east-1`
AWS Role ARN	Role-Based	ARN printed by the setup script	`arn:aws:iam::123456789012:role/CloudThinkerAccessRole`
AWS External ID	Role-Based	Generated by CloudThinker. Read-only, must match the trust policy.	Filled in for you
AWS_ACCESS_KEY_ID	Access Keys	The IAM user’s access key ID	`AKIA...`
AWS_SECRET_ACCESS_KEY	Access Keys	The IAM user’s secret key	Shown once by AWS

Environment (Production, Staging, Development, or Not set) isn’t in the connect dialog. Set it after connecting, as in the last setup step: it labels the account for people and agents. Approval rules don’t read it, so a Rule that should cover one account names that connection.

Required permissions

The setup scripts attach the AWS managed ReadOnlyAccess policy. It lets agents describe and list resources across services, read CloudWatch metrics, and read Cost Explorer. It can’t create, change, or delete anything.

You want	Grant
Inventory, health, and security questions	`ReadOnlyAccess` (what the script attaches)
Optimize cost data	Included in `ReadOnlyAccess`. With a custom policy, add `ce:Get*`.
Agents to make specific changes	Add only those actions to the role, then see Write access

ReadOnlyAccess can read data as well as configuration, such as S3 objects. A narrower option is AWS managed ViewOnlyAccess plus SecurityAudit, with the ce:Get* reads added for Optimize. It covers listing and describing resources, but not data reads such as S3 object contents or log events. A missing permission never disconnects the account: the answer that needed it fails with AccessDenied, which names the missing action, so you can add just that action to the inline policy.

To switch an existing role to the narrower set, run this in CloudShell:

ROLE=CloudThinkerAccessRole
aws iam attach-role-policy --role-name $ROLE --policy-arn arn:aws:iam::aws:policy/job-function/ViewOnlyAccess
aws iam attach-role-policy --role-name $ROLE --policy-arn arn:aws:iam::aws:policy/SecurityAudit
aws iam put-role-policy --role-name $ROLE --policy-name CloudThinkerCostRead \
  --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"ce:Get*","Resource":"*"}]}'
aws iam detach-role-policy --role-name $ROLE --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

In Terraform, replace the read_only attachment with attachments for those two policy ARNs and an aws_iam_role_policy holding the ce:Get* statement.

Agent capabilities

Area	What CloudThinker does
Inventory	Lists and describes compute, storage, networking, and managed services across regions
Identity	Reviews IAM roles, users, and policies for risky or unused access
Cost	Breaks down spend by service, account, and tag, and checks Reserved Instance and Savings Plans coverage. Feeds Optimize.
Monitoring	Reads CloudWatch metrics and alarms to explain a spike or an outage
Changes	Runs AWS CLI writes only when Allow writes is on, the role permits them, and your approval settings allow them

Verify the connection

Which AWS account ID and regions can you reach through my AWS connection?

The answer names your real 12-digit account ID.

Example prompts

Break down last month's AWS spend by service and flag anything that grew more than 20% from the month before
List IAM users and roles that haven't been used in 90 days
Find EC2 instances in us-east-1 with average CPU under 10% over the last two weeks

Write access

Allow writes on the connection’s detail panel controls whether agents may change anything in AWS. It’s on by default for AWS, but the role the script creates is read-only, so AWS itself refuses every write until you grant more.

IAM permissions	Allow writes	Result
`ReadOnlyAccess` only	On or off	Read-only. AWS rejects any change.
Extra write actions granted	Off	Read-only. CloudThinker refuses every change before it reaches AWS.
Extra write actions granted	On	Agents can propose changes. Your Rules and Approval mode decide each one.

To lock writes in CloudThinker as well, open Amazon Web Services in More → Workspace settings → Connections and turn off the Allow writes switch on its detail panel.

Troubleshooting

The script says CloudThinkerAccessRole already exists

Cause: an earlier setup in this account created the role, likely with a different External ID.Fix: if no other CloudThinker connection uses that role, remove its policies and delete it, then run the new script. delete-role fails until every attached and inline policy is gone, so list them first:

ROLE=CloudThinkerAccessRole
aws iam list-attached-role-policies --role-name $ROLE
aws iam list-role-policies --role-name $ROLE
# For each attached policy ARN:
aws iam detach-role-policy --role-name $ROLE --policy-arn <policy-arn>
# For each inline policy name:
aws iam delete-role-policy --role-name $ROLE --policy-name <policy-name>
aws iam delete-role --role-name $ROLE

To check whether a CloudThinker connection still uses the role, open CloudTrail Event history, filter Event name = AssumeRole, and look for recent events on CloudThinkerAccessRole with a session name starting cloudthinker-. If one does, don’t replace its External ID. Use Manual steps to create a second role with a different name for this workspace instead.

The test fails with AccessDenied on sts:AssumeRole

Cause: the trust policy doesn’t match what CloudThinker presents.Check: the ARN you pasted is the one the script printed, and the trust policy’s sts:ExternalId matches AWS External ID in the dialog exactly.Fix: a failed test doesn’t save the connection. Correct the trust policy, then click Connect again in the same dialog so the External ID stays the same. If you closed the dialog, re-run the setup from a fresh one. Retry appears only on a saved connection that later shows Error.

The connection shows Error and scheduled work stopped

Cause: three background credential failures in a row (a deleted role, a broken trust policy, or a revoked key) switch the connection to Error. Optimize cost refreshes, scheduled automations, and Pulse polling pause for it, and workspace admins get one notification.Fix: repair the role or key in AWS, then click Retry on the connection, or Replace credentials to enter new keys. Scheduled work resumes on its next cycle once the status is Connected.

Cost questions return no data

Check: Cost Explorer is turned on in the AWS Billing console, and at least 24 hours have passed since you turned it on. For a member account in AWS Organizations, the management account may block member access to Cost Explorer.Fix: turn on Cost Explorer, or connect the management account to see costs for the whole organization.

The test shows Timed out

Cause: the test didn’t finish in time. AWS endpoints are public, so it’s rarely your network.Fix: connect again. If it keeps timing out, contact us.

A region or service returns AccessDenied with an explicit deny

Cause: a service control policy blocks it. The AWS error says the request was denied with an explicit deny in a service control policy. If the SCP denies sts:AssumeRole, the test itself fails.Check: list the SCPs on the account, as in Prerequisites.Fix: ask your AWS Organizations admin to exempt CloudThinkerAccessRole from the SCP, or accept that agents can’t see that region or service.

Security

Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

Prefer the role. CloudThinker assumes the role through AWS STS and gets short-lived credentials, so there’s no long-lived secret to leak. The External ID stops anyone else from using your role through CloudThinker.
Audit with CloudTrail. Every call agents make is an ordinary AWS API call. CloudThinker names each role session cloudthinker-<first 8 characters of your workspace ID>-<Unix timestamp>, and CloudTrail Event history shows that session name as the User name. To see every call across sessions, filter on userIdentity.sessionContext.sessionIssuer.userName = CloudThinkerAccessRole in CloudTrail Lake or Athena. For access keys, filter Event history by User name = CloudThinkerUser.

Optimize quickstart

Turn this connection into cost findings and savings recommendations.

Connections

Rotate credentials, set the environment, and read Discovery results.

Approvals

Decide which changes need a person before you grant any write permission.

Connections

Customize

Approvals

Workspace settings

Admin Settings

Artifacts and sharing

Prerequisites

Setup

Connect more accounts

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Write access

Troubleshooting

Security

Optimize quickstart

Connections

Approvals

​Prerequisites

​Setup

​Connect more accounts

​Connection details

​Required permissions

​Agent capabilities

​Verify the connection

​Example prompts

​Write access

​Troubleshooting

​Security

​Related

Optimize quickstart

Connections

Approvals

Prerequisites

Setup

Connect more accounts

Connection details

Required permissions

Agent capabilities

Verify the connection

Example prompts

Write access

Troubleshooting

Security

Related