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 or a permission.
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 in that deployment's region. Request it in ACM with DNS validation (the Organisations console certificate in row 3 has no such constraint): the deploy requests the us-east-1 certificate CloudFront needs with DNS validation, and it validates on the same CNAME only when the regional certificate was DNS-validated (Deploy your first Studio). |
| 5 | DNS control | One CNAME for the Organisations console, one per Studio deployment. |
| 6 | 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). |
| 7 | A workstation | Python 3.11 or later with boto3 (python3 -m pip install boto3), plus crane or regctl, or Docker with its daemon running. |
| 8 | Outbound HTTPS | From the workstation and from both VPCs (through their NAT gateways) to AWS and to telemetry.api.alphaagent.prometheusrl.com (every outbound call). |
| 9 | Amazon Bedrock model access | In each Studio account's region, for Claude Sonnet 4.6, Claude Opus 4.6 (and Opus 4.7 or 4.8 if chosen) and Cohere Embed v4. Nothing checks this; a missing model surfaces after the stacks exist (Supported models). |
| 10 | IAM and an SCP review | The identities below, and your service control policies (SCPs) checked against SCPs and guardrails. |
| 11 | A private /16 per account | Not overlapping an existing VPC or a network you may peer with. The installer asks for the Organisations range (default 10.70.0.0/16); the Studio range is not asked and uses 10.60.0.0/16. |
| 12 | 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. Every Studio account also uses us-east-1 for its CloudFront front door, so the account template's AllowedRegions must keep it. |
IAM permissions: three identities and one role
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 six 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). 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
elasticloadbalancing:DescribeTargetHealth, DescribeListeners
dynamodb:PutItem, Scan, DescribeTable, UpdateTable, DeleteTable (teardown)
ec2:DescribeAvailabilityZones, DescribeVpcs, DescribeAddresses
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), 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, retained if the stack is deleted
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 access only) 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. Bedrock model access, Fargate vCPU quotas and Bedrock token quotas are not checked either.
What the installer checks against this list
orgctl.py runs fifteen preflight checks before creating anything. A FAIL stops the install ("Nothing has been created, so this is free to repeat."); a WARN continues. The Studio deploy job runs the account-side checks against the Studio account and parks instead of failing. 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 each) | WARN, never FAIL; SKIP when Service Quotas is unreadable |
vpc-cidr-overlap | The /16 does not overlap an existing VPC | FAIL naming the VPCs |
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 | FAIL |
Notes
- The deploy job reads back one region control: the registration stack's
AllowedRegionsandTemplateVersion. It refuses withregistration_stack_stale_for_cloudfrontwhenus-east-1is missing or the 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.