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.
Before you start
For the administrator who owns the AlphaAgent relationship and the cloud engineer who runs the installer: read this once, before you create anything, so that no step waits on a person, a certificate, a network change or a permission.
Every new install is private: the Organisations console and each Studio deployment sit behind an internal load balancer in your AWS account, reached over your Transit Gateway, with no CloudFront. Your network team's part is on Private network access.
The pages of this section run in order. A later Studio deployment repeats only the licence key, the account registration and the deploy.
Have these ready
| # | Item | Detail |
|---|---|---|
| 1 | Fresh AWS accounts | One new, empty account for Organisations and one per Studio deployment, for the reasons above. |
| 2 | A buyer account | Accepts the private offer; accepting deploys nothing, it decides whose AWS bill carries the charges. Use the Organisations account; one Console account links to exactly one buyer account. |
| 3 | Console hostname and certificate | A hostname you control (org.example.com) and an AWS Certificate Manager (ACM) certificate for it, status Issued, in the install region; the load balancer cannot use one from another region. |
| 4 | Studio hostname and certificate | Per deployment: an app hostname (studio.example.com) and an Issued ACM certificate for it in that deployment's region. Nothing is requested in us-east-1. |
| 5 | A Transit Gateway | In each region you install into, owned by the account or shared with it through AWS Resource Access Manager with the share accepted, and a network team ready to accept each attachment request (Private network access). |
| 6 | Network ranges | A VPC range for Organisations and one per Studio deployment, unique on your routed network; the ranges your administrators and users connect from; for Studio, the ranges and extra ports of the internal services agents may reach. |
| 7 | Private DNS | One record for the console hostname and one per Studio app hostname, in a private hosted zone (or resolver rules) your users resolve, associated with each AlphaAgent VPC. |
| 8 | Outbound internet traffic | Through AlphaAgent's NAT gateway, or through your Transit Gateway and your firewall. With your firewall: its public egress IP addresses and the allow-list on Private network access. The workstation needs HTTPS to AWS and to telemetry.api.alphaagent.prometheusrl.com. |
| 9 | An Entra ID administrator | Creates a non-gallery SAML enterprise application and assigns users; creates a multi-tenant app registration with a client secret and grants admin consent for five Microsoft Graph application permissions (a Global Administrator). |
| 10 | A workstation | Python 3.11 or later with boto3 (python3 -m pip install boto3), plus crane or regctl, or Docker with its daemon running. To check sign-in from the installer, it must also be on a network routed to the Organisations VPC. |
| 11 | Amazon Bedrock model access | In each Studio account's region, for Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5 and Cohere Embed v4 through their us. or eu. inference profiles. Before you install or upgrade, enable access in the Amazon Bedrock console (Model access) in that account and region. The deployment preflight refuses a model the account cannot invoke, and warns on a missing model agreement or a Bedrock quota below its recommended floor (Supported models). |
| 12 | IAM and an SCP review | The identities below, and your service control policies (SCPs) checked against SCPs and guardrails. |
| 13 | Regions | One of us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-west-3, eu-central-1, eu-central-2, eu-north-1, eu-south-1, eu-south-2 (the regions serving the US or EU Bedrock inference profiles) per account. A private deployment needs no other region: register each Studio account with only the regions you use in AllowedRegions, its deployment region first. |
IAM permissions: three identities and one role
Installing Organisations and registering each Studio account involve three identities and one role; the IAM permissions each one needs are below.
The identity that runs the installer. orgctl.py resolves it once with sts:GetCallerIdentity (the default boto3 chain, or --profile <name>) and installs into that account. It creates the seven stacks with cloudformation:CreateStack and change sets, without a CloudFormation service role, so every resource is created with your identity's own permissions: "They need permission to create VPC networking, an Application Load Balancer, ECS, ECR, Lambda, DynamoDB, S3, Secrets Manager, Cognito, IAM roles and CloudWatch log groups." Only alphaagent-org-app needs CAPABILITY_NAMED_IAM (three named roles), and alphaagent-org-private-network needs CAPABILITY_AUTO_EXPAND. No policy file ships in the bundle yet; besides CloudFormation's creates, the installer calls these actions directly:
sts:GetCallerIdentity
cloudformation:DescribeStacks, DescribeStackEvents, CreateStack, CreateChangeSet, DescribeChangeSet,
ExecuteChangeSet, DeleteChangeSet, DeleteStack (teardown)
acm:ListCertificates, DescribeCertificate
ecr:DescribeRepositories, DescribeImages, GetAuthorizationToken, BatchCheckLayerAvailability,
InitiateLayerUpload, UploadLayerPart, CompleteLayerUpload, PutImage, BatchGetImage,
DeleteRepository (teardown)
s3:PutObject, GetBucketCors, ListBucket, GetObject, DeleteObject, DeleteBucket (teardown)
secretsmanager:GetSecretValue, PutSecretValue, CreateSecret, DescribeSecret, DeleteSecret (teardown)
cognito-idp:DescribeUserPool, DescribeUserPoolClient, UpdateUserPoolClient, ListIdentityProviders,
DescribeIdentityProvider, CreateIdentityProvider, UpdateIdentityProvider,
DescribeUserPoolDomain, AdminCreateUser, UpdateUserPool, DeleteUserPoolDomain,
DeleteUserPool (teardown)
ecs:DescribeServices, UpdateService, ListTasks, DescribeTasks, DescribeTaskDefinition,
RunTask, StopTask (the outbound traffic check, with Transit Gateway egress)
iam:PassRole on the Organisation's task and execution roles (that check's task)
iam:GetRole, CreateServiceLinkedRole on role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS
elasticloadbalancing:DescribeTargetHealth, DescribeListeners
dynamodb:PutItem, Scan, DescribeTable, UpdateTable, DeleteTable (teardown)
ec2:DescribeAvailabilityZones, DescribeVpcs, DescribeAddresses, DescribeTransitGateways,
DescribeVpcEndpointServices, DescribeVpcEndpoints, DescribeTransitGatewayVpcAttachments,
CreateTransitGatewayVpcAttachment, CreateTags, DeleteTransitGatewayVpcAttachment (teardown),
DescribeRouteTables, CreateRoute, DescribeSecurityGroupRules, DescribeNetworkInterfaces,
DescribeManagedPrefixLists, GetManagedPrefixListEntries
logs:FilterLogEvents (the outbound traffic check's report)
servicequotas:GetServiceQuota (advisory: the quota-headroom check skips without it)
logs:DeleteLogGroup, ssm:DeleteParameter (teardown only)
The identity that runs the account template. In each Studio account it creates one stack, alphaagent-org-target-<account id>, from a time-limited template URL (valid seven days), in the account's first allowed region, acknowledging CAPABILITY_NAMED_IAM: iam:CreateRole and iam:AttachRolePolicy for one named role with four (optionally five) managed policies, plus s3:CreateBucket and the bucket settings for one staging bucket.
The buyer identity. Acts only in AWS Marketplace (view the offer, accept it, Set up your account); the product does not name its aws-marketplace actions. The Studio task role carries aws-marketplace:ViewSubscriptions, Subscribe and Unsubscribe so that Bedrock can serve Marketplace-hosted models.
The role the template creates. AlphaAgentOrgTarget-<suffix> under /alphaagent-org/, one-hour sessions, a fresh one per job step:
Trust only arn:aws:iam::<Org account id>:role/alphaagent-org-task-role, with your sts:ExternalId
Deny (AlphaAgentOrgTargetGuardrails; wins over every allow)
DenyAccountAndOrganizationControl organizations:*, account:*, iam:CreateUser, iam:CreateAccessKey,
iam:CreateLoginProfile, iam:UpdateLoginProfile, iam:DeleteLoginProfile,
sts:GetFederationToken, sts:TagSession
DenyRoleMutationOutsideAlphaAgent iam:CreateRole, DeleteRole, UpdateRole, UpdateAssumeRolePolicy,
AttachRolePolicy, DetachRolePolicy, PutRolePolicy, DeleteRolePolicy,
PassRole on any role not named alphaagent*/AlphaAgent* or service-linked
DenyStudioUserImpersonation cognito-idp:AdminCreateUser, AdminSetUserPassword, AdminInitiateAuth,
AdminRespondToAuthChallenge, AdminUserGlobalSignOut
DenyOutsideAllowedRegions every action outside AllowedRegions, except iam, sts, organizations,
account, cloudfront, route53, support and two account-level S3 reads
Allow (AlphaAgentOrgTargetStacksAndCompute)
cloudformation:*, ec2:*, elasticloadbalancing:*, ecs:*, servicediscovery:*, autoscaling:* on all
iam:* on roles named alphaagent*, AlphaAgent* and aws-service-role/*; iam:ListRoles on all
Allow (AlphaAgentOrgTargetDataAndStorage)
dynamodb:* on tables alphaagent*; s3:* on buckets alphaagent* and alphaagent-org-staging-<account>-*
secretsmanager:* on secrets alphaagent*
dynamodb:ListTables, s3:ListAllMyBuckets, s3:GetBucketLocation, secretsmanager:ListSecrets,
secretsmanager:GetRandomPassword on all
sqs:*, sns:*, events:*, elasticache:*, elasticfilesystem:* on all
kms:* only via S3, Secrets Manager, DynamoDB, SQS, SNS, ElastiCache, EFS, CloudWatch Logs or ECR
Allow (AlphaAgentOrgTargetAppAndProbe)
logs:*, cloudwatch:*, ssm:*, lambda:*, cloudfront:* (template 2.3.0, for the front door), ecr:*,
cognito-idp:* (minus the denied impersonation actions), acm:*, servicequotas:*, sts:*, bedrock:*
Allow (AlphaAgentOrgTargetApiWaf; only with EnableApiWafPermissions=true)
wafv2:* on regional web ACLs, IP sets and load balancers named alphaagent*;
wafv2:CheckCapacity, ListWebACLs, ListIPSets
Staging bucket (CreateStagingBucket=true)
alphaagent-org-staging-<account>-<region>: SSE-S3, all four public-access blocks on,
staged templates expire after seven days, deleted with the stack (once empty)
The Organisation never creates IAM users or access keys in your accounts. A permissions boundary on the role is invisible to Verify (which tests sts:AssumeRole, and us-east-1 only where the role allows it) and surfaces as denies during a job.
SCPs and missing permissions
No preflight check enumerates your policy. A missing permission or a deny (a service control policy, a permission boundary, a tag rule) surfaces during the install as a FATAL line, or on a job's failure card, naming the denied action: grant it and re-run the same command. Review your SCPs against SCPs and guardrails first. Fargate vCPU quotas are not checked either; Bedrock model access and Bedrock token quotas are checked by the Studio deployment's preflight, not by the installer.
What the installer checks against this list
orgctl.py runs twenty-one preflight checks before creating anything. A FAIL stops the install ("Nothing has been created, so this is free to repeat."); a WARN continues; a SKIP does not apply to your answers. The Studio deploy job runs the account-side checks against the Studio account and parks instead of failing, except that a Transit Gateway the account cannot see fails the job with transit_gateway_not_visible, and a selected model the account cannot invoke fails it with bedrock_model_access_refused. Remediations: Troubleshooting the install.
| Check | Verifies | Outcome when not met |
|---|---|---|
python-version | Python 3.11 or newer | FAIL |
boto3 | boto3 importable | FAIL |
docker-daemon | docker CLI and daemon | WARN if crane or regctl is present, else FAIL |
image-copier | crane or regctl on the PATH | WARN |
release-manifest | RELEASE.txt parses | SKIP when absent, else FAIL |
bundle-complete | Every mandatory bundle member present | FAIL, listing the missing members |
caller-identity | Credentials resolve to the intended account | FAIL |
region-allowed | One of the eleven regions | FAIL, then the list |
availability-zones | At least two usable zones | FAIL with the count |
quota-headroom | Elastic IP, VPC and NAT gateway headroom (one VPC; with the NAT gateway also one Elastic IP and one NAT gateway) | WARN, never FAIL; SKIP when Service Quotas is unreadable |
ecs-service-linked-role | ECS's service-linked role exists, or the install creates it before the first cluster | PASS in a fresh account (the install creates the role and waits for it); WARN when it cannot be read, naming iam:GetRole and iam:CreateServiceLinkedRole |
vpc-cidr-overlap | The VPC range does not overlap an existing VPC in the account | FAIL naming each VPC, its stack and its deployment |
vpc-range-capacity | Each private subnet of the VPC range has room for what this release runs there | FAIL naming the smallest range that fits |
transit-gateway-visible | The Transit Gateway is visible in this account and region, and whether it accepts attachments automatically | FAIL: "Check the Transit Gateway ID and region. A Transit Gateway owned by another account must be shared with this account through AWS Resource Access Manager, and the share accepted in this account." |
egress-endpoints-available | With outbound traffic through your Transit Gateway, every AWS endpoint the install creates is offered in the zones it uses | FAIL naming the service and zone; SKIP with the NAT gateway |
bedrock-model-access | The selected models can be invoked in this account and region | SKIP in the installer ("No models selected (this check runs for a Studio deployment)"); for a Studio deployment, FAIL on a missing inference profile, an account not authorised or a model not available in the region, WARN on a missing model agreement |
bedrock-model-quotas | Bedrock quotas for the selected models meet the recommended floors | SKIP in the installer; for a Studio deployment, WARN, never FAIL, naming the quota, its value and the floor |
cognito-prefix | alphaagent-<account id>-<region> is free | WARN when unreadable or held by this Organisation's own pool; FAIL for another pool |
acm-certificate | An Issued in-region certificate covers the hostname | FAIL |
dns-resolves | The console hostname resolves | WARN, expected on a first install |
wedged-stacks | No earlier Organisations stack is stuck failed | WARN for a failed first create that kept nothing ("Nothing to do: the install deletes it and creates it again."); FAIL for every other stuck state |
Notes
- A private deployment never reads the registration stack for us-east-1. Only an update of an existing public deployment does, and refuses with
registration_stack_stale_for_cloudfrontwhenus-east-1is missing or the template version is older than 2.3.0. - Measured: an Organisations install takes about 20 minutes wall clock from the first prompt to the Done banner; a Studio deployment 45 to 50 minutes.