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 first allowed region: the registration stack is created there, the wizard sets a deployment's region from it, and Clear account operates on it. More can be added later; none can be removed. For a private deployment, choose the region the deployment and your Transit Gateway are in. - 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 and check that Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5 and Cohere Embed v4 can be used there (Model access and Bedrock quotas). The deployment's preflight checks this through the role you create below: it refuses a model the account cannot invoke, and warns when a model agreement is missing (Studio's first call to the model accepts it) or when a Bedrock quota is below its recommended floor.
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 (served by the Organisations console itself) and Launch the stack in the AWS console, with the line "The stack is created in <region>."; 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 in the account's first allowed region 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. A private deployment needs only its own region: narrow the list to the regions you use, with the account's first region (the one the stack is created in) on it. Keep us-east-1 only for an account that holds a public deployment created before private network access, whose CloudFront front door lives 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), and false when you register the account again in a region where a bucket from an earlier registration is still there |
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 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; skipped when AllowedRegions leaves us-east-1 out ("us-east-1 is not allowed for this account, so nothing there was checked. CloudFront is used only by Public deployments.") |
Last Clear account left nothing behind (account-clear) | "No Clear account has finished for this account." on a fresh account |
Removed deployments' VPC ranges are released (vpc-ranges-released) | Shown only while a removed deployment of the account still holds a VPC range; passes once its VPC is gone and releases the range in the Address plan |
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 only to update an existing public deployment's CloudFront front door; an older registration is flagged then and needs its stack updated from the current template. Private deployments never need it. - Accounts registered before the launch link followed the first allowed region keep their stack where it already is (often the Organisation's own region).
- The staging bucket holds only staged copies that expire after seven days. From this template it is deleted with the stack. A bucket that still holds staged copies stops the stack delete with "The bucket you tried to delete is not empty": run Clear account first (it empties the bucket), or empty it, then delete the stack again. A stack created from an earlier template keeps the bucket when it is deleted: update the stack from the current template (Download org-target-account-role.yaml, then update the stack in CloudFormation with the same parameters) before you delete it, or empty and delete a bucket an earlier registration left behind yourself. Deleting the stack that created the bucket also removes it for any second role registered with
CreateStagingBucketset tofalse, so delete that stack last. - Delete on the account page removes only the Organisations record, names the stack to delete in AWS if you want the role gone ("it removes the
<role>role too"; with the current template it removes the staging bucket as well), 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.