Install AlphaAgent Organisations into a new, empty AWS account, and give every AlphaAgent Studio deployment a new, empty AWS account of its own. Three reasons:
- It is AWS best practice to isolate each workload in its own account, with its own limits, billing view and permissions.
- Amazon Bedrock quotas are set per AWS account. Many users in one deployment share one quota and exhaust it; one account per deployment keeps each team's capacity its own.
- The blast radius is smaller. A problem in one deployment, or one team's mistake, cannot reach the others.
Register an AWS account
For the owner, operator or AccountManager who registers and verifies in the console, and whoever holds administrator access to the fresh Studio account and runs the template there (it creates a named IAM role). Before you start: the account's 12-digit id and region, and doctor passing target-account-role-template.
1. Add the account
- Open Accounts (headed AWS Accounts) and click Add an account (disabled tooltip: "Requires the AccountManager role (or owner/operator)").
- On Add an AWS account fill in Alias (placeholder
acme-production), AWS Account ID (twelve digits;1234-5678-9012grouping accepted) and Region (the eleven supported regions, labelled likeus-east-1 (N. Virginia)). It becomes the account's allowed region: the wizard sets a deployment's region from it and Clear account operates on it; more can be added later. - Click Register AWS account. The account's page opens with Status "Pending".
2. Enable Bedrock model access
In the Studio account, open the Amazon Bedrock console in the account's region, choose Model access, and enable Claude Sonnet 4.6, the Claude Opus version you will pick (4.6 by default) and Cohere Embed v4 (Enable model access before you deploy). Nothing later checks this: a missing model surfaces only once the Studio is running.
3. Read the account page
Account details shows Alias, Region(s) (with Add a region... and Add region), Role ARN (arn:aws:iam::<account id>:role/alphaagent-org/AlphaAgentOrgTarget-prod) and External id, a 32-character value generated for this account alone. Run the template (shown while Pending or Failed) gives Trust policy must name (arn:aws:iam::<organisation account id>:role/alphaagent-org-task-role), Template version, Download org-target-account-role.yaml and Launch the stack in the AWS console; below sit Verify, Clear account and Metadata.
4. Run the template in the target account
Either click Launch the stack in the AWS console, which opens CloudFormation's Create stack page with the template loaded, the stack name alphaagent-org-target-<account id> and OrgAccountId, OrgTaskRoleName, ExternalId and RoleNameSuffix pre-filled (sign in to the target account in that tab, keep the other defaults, tick the IAM acknowledgement, create), or download the template, review it and deploy it yourself with CAPABILITY_NAMED_IAM, pasting the external id rather than scripting it. One role and one bucket; measured, about one minute.
| Parameter | Enter |
|---|---|
| OrgAccountId | The Organisation's 12-digit account (the account in Trust policy must name) |
| OrgTaskRoleName | alphaagent-org-task-role unless installed with a custom name |
| ExternalId | The External id exactly (hidden as you type; compare the printed 12-character fingerprint with printf %s '<the id>' | shasum -a 256 | cut -c1-12) |
| RoleNameSuffix | prod; the role is AlphaAgentOrgTarget-<suffix> |
| AllowedRegions | All eleven regions by default; if narrowed, keep your region and us-east-1 (the CloudFront front door's edge function and certificate live there) |
| EnableApiWafPermissions | false unless you will put a network allow-list in front of a Studio public API; true adds one policy for WAF web ACLs and IP sets named alphaagent* |
| CreateStagingBucket | true for the first role in this account and region; false for a second role there (one bucket per account and region) |
Outputs: RoleArn, StagingBucketName (alphaagent-org-staging-<account id>-<region>), TemplateVersion (2.3.0).
5. Verify
Back on the account page click Verify this account ("Running nine checks..."). The Verification result box lists:
| Check | Pass or skip reads |
|---|---|
Assume the target role (assume-role) | "Successfully assumed <role arn>." |
Retry CloudFront edge stacks waiting on Lambda@Edge replica cleanup (edge-cleanup) | "No edge stack is waiting on Lambda@Edge replica cleanup in us-east-1." on a fresh account |
Last Clear account left nothing behind (account-clear) | "No Clear account has finished for this account." on a fresh account |
What you should see
Status reads Verified and Run the template disappears; "Last verification:" shows the outcome with a Deploy Studio into this account link. Accounts lists the account (Alias, Account, Regions, Status, Deployments, Last verified); Home drops it from Accounts needing verification; the deploy wizard's Target account list offers it (unverified accounts read "Not verified yet").
Notes
- The role has one-hour sessions and is trusted only by your Organisation's task role presenting your external id; its deny guards block account and organisation control, IAM role mutation outside
alphaagent*names, Cognito impersonation of Studio users, and every regional action outside AllowedRegions. Statement by statement: Before you start. - Template version
2.3.0withus-east-1in AllowedRegions is required for the CloudFront front door; an older registration is flagged when you deploy and needs its stack updated from the current template. - The Verify label says "nine checks"; three run.
- Delete on the account page removes only the Organisations record, names the stack to delete in AWS if you want the role gone, and warns that a leftover role makes re-registration fail because it already exists. An account with deployments cannot be deleted.
- Clear account ("Scan this account and region for every AlphaAgent resource still there, then permanently delete it") resets an account before re-registering or finishes a removal; the registration role and stack are preserved: Deleting a deployment and clearing an account.