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.
Install Organisations
For the cloud engineer with AWS credentials for the fresh Organisations account and Python on a workstation; the Console administrator generates the credential. Before you start: everything on Before you start, and the network items on Private network access. The SAML metadata (step 10) can be prepared while the early steps run.
1. Get the credential and the bundle
- In the AlphaAgent Console, open Organisation. On the credential card click Generate credential, then in Credential created click Copy token and store the value: it is shown once, and the installer keeps it in AWS Secrets Manager in your account. Viewers cannot generate, rotate or revoke.
- Under Organisation bundle the newest row is labelled "latest"; older rows read "Superseded" and cannot be downloaded. Click Download bundle (the link is short-lived). The file is
alphaagent-org-cfn-bundle-<version>.zipwith dashes for dots, for examplealphaagent-org-cfn-bundle-1-0-16.zip. - Unzip into a fresh, empty directory and keep the layout:
orgctl.pyimports the modules beside it and writes its progress file here. ReadREADME.mdandRELEASE.txt; the templates undercloudformation/are there for your review (Everything AlphaAgent deploys). No checksum is published; thebundle-completecheck catches a short download.
2. Start the installer and answer the questions
With AWS credentials set in the shell (AWS_PROFILE, or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY), run:
python3 orgctl.py
The banner "AlphaAgent Organisations installer" reports "No install recorded on this machine." (or "An install is already under way here: N/13 steps done.") and asks Start the install now?; Yes equals python3 orgctl.py install. Every question shows its default in brackets; Enter accepts it; answers are remembered.
| Question | Answer | Default |
|---|---|---|
| "AWS region to install AlphaAgent Organisations into" (a menu) | The region your certificate was issued in and your Transit Gateway is in; skipped with --region or AWS_REGION. | none |
| "Is this the correct AWS account and region?" (after AWS account, Identity, Region) | Check the id is the fresh Organisations account; No prints "Stopped; nothing was changed." | Yes |
| "How do you want to proceed?" | Only when an Organisation or checkpoints already exist: the Resume menu (Troubleshooting the install). | Resume |
| "Environment": prod, staging or dev | Part of every resource name. | prod |
| "Hostname your team will use for the Organisations console" | Hostname only, lower case, no scheme (org.example.com). | required |
"ARN of the ACM certificate for that hostname, issued in <region>" | Enter: the installer prints "Found an issued certificate covering <host>" and offers the match (or lists several). | the match |
| "Outbound internet traffic from the Organisation VPC" | Through AlphaAgent's NAT gateway or Through your Transit Gateway (your firewall). Set once. | none |
| "VPC range for the Organisation, a private /16 to /24" (/23 with the NAT gateway) | A private range unique on your routed network. The installer first prints "A /24 is enough for the Organisation with egress through your Transit Gateway." (or "A /23 ... with AlphaAgent's NAT gateway."). Set once. | none |
"Transit Gateway ID in <region>, for example tgw-0123456789abcdef0" | The Transit Gateway your administrators reach the console over. | required |
| "Ranges your administrators connect from, comma separated" | Up to 10 private ranges; only these are routed to the console. | required |
| "Your firewall's public egress IP addresses, comma separated" | Only with outbound traffic through your Transit Gateway: 1 to 8 public IPv4 addresses. | required |
| "Email address for the Organisation's first owner and break-glass administrator" | Your own address, spelt as your identity provider sends it; it gets the owner role and is the only sign-in left if single sign-on breaks. | required |
| "Proceed?" after the Summary | Check it: account, Identity, Region, Environment, Console URL, Certificate, Sign-in domain <prefix>.auth.<region>.amazoncognito.com, VPC and its private subnets (and NAT subnets), Console access "private", Transit Gateway, Admin ranges, Outbound traffic (and Egress IPs), Break-glass admin, Console endpoint, the seven stacks alphaagent-org-auth, -data, -jobs, -release-cache, -foundation, -private-network, -app. With outbound traffic through your Transit Gateway it also prints the hosts your firewall must allow. | Yes |
The console is always private on a new install, so there is no question for it: the installer prints "Console network access: private (the load balancer sits in the Organisation VPC's private subnets, reached over your Transit Gateway)". console_access: public in --config is refused before anything is created. The sign-in prefix is derived, not asked: alphaagent-<account id>-<region> (preset only through --config). "Release tag to push" and "AlphaAgent Console base URL" are asked only when RELEASE.txt lacks them, never with a downloaded bundle; two more questions arrive inside steps 10 and 11.
3. The thirteen steps
Each step prints "Step N/13 - <label>", is checkpointed when it finishes, and prints "already done, skipping" on a later run. Stack creation streams CloudFormation events to the terminal.
1/13 Preflight checks. Runs the twenty-one checks from Before you start and prints a table (STATUS, CHECK, WHAT IT VERIFIES), a -> remediation under each non-passing row, then "N passed, N warning(s), N failed, N skipped". WARN continues; any FAIL stops with "Nothing has been created, so this is free to repeat." Records the confirmed account and region.
2/13 Sign-in stack (Cognito) and the SAML service-provider values. Creates alphaagent-org-auth (the user pool, its sign-in domain, the load balancer's app client), then prints the box FOR YOUR IDENTITY ADMINISTRATOR with the Identifier, Reply URL, Sign-on URL, provider name and three required claims, also written to org-saml-sp-values.txt. Hand it over now: Sign in with Entra ID.
3/13 Foundation and data stacks. Creates alphaagent-org-data, alphaagent-org-jobs and alphaagent-org-release-cache concurrently, then alphaagent-org-foundation: the VPC and its private subnets, the VPC endpoints, security groups, S3 buckets, the ECR repository, six empty Secrets Manager secrets and log groups; with the NAT gateway also the two NAT subnets, the internet gateway and the NAT gateway, and with your Transit Gateway none of those. It also creates ECS's service-linked role if the account has never run ECS. Allow 15 to 20 minutes (the installer's own estimate).
4/13 Private network (Transit Gateway attachment and routes). Requests the attachment of the VPC's private subnets to your Transit Gateway and, unless it accepts attachments automatically, prints "Waiting for you: accept the Transit Gateway attachment <attachment id> in the account that owns <tgw id> (<owner account>). It connects the Organisations VPC <vpc id> in <account>. Press Enter once it is accepted." With --yes it checks every 30 seconds for up to an hour, then stops with "Re-run python3 orgctl.py install to continue once it is accepted." Once the attachment is available it creates alphaagent-org-private-network: a route per administrator range to the Transit Gateway, the console load balancer's access from those ranges, and, with outbound traffic through your Transit Gateway, the default route to it, the interface endpoints and the route that drops other private ranges (Private network access). A rejected or deleted attachment stops the run; re-running makes a new request.
5/13 Push the Organisation image to your registry. Pushes image.tar.gz as alphaagent-org:<version> into the repository with crane, regctl or Docker, printing "image transport: <tool>", "authenticated to <registry>" and the digest, or "already in <repo> ... - skipping".
6/13 Write the application's configuration secrets. Fills the configuration secrets; mints the service signing key and the internal API key once and preserves them on every later run ("minted", "preserved (unchanged)", "updated (N keys)"). It also adds any administrator missing from the console's Admins page to it, with the role they already hold. The console credential secret is left to step 10.
7/13 Upload the Organisations console. Uploads the spa/ files to the console bucket and confirms its CORS rule allows https://<hostname>.
8/13 App stack (ALB, cluster, services). Creates alphaagent-org-app: the internal Application Load Balancer in the private subnets with Cognito authentication, the ECS cluster with the org-api and org-provisioner services, the console-serving Lambda; stages org-target-account-role.yaml for the Accounts screen. If ECS was still preparing its service-linked role when the cluster was created, it deletes the stack and creates it once more by itself. Ends by printing where to point the hostname: create the record now.
Point org.example.com at internal-alphaagent-org-<env>-alb-<id>.<region>.elb.amazonaws.com in the private DNS zone your administrators resolve, and associate that zone with VPC vpc-0123456789abcdef0.
9/13 Wait for services to reach steady state. With outbound traffic through your Transit Gateway it first runs one short task in the private subnets that connects to every host on the firewall list and checks each certificate; it stops, naming each host your firewall blocks, inspects or resets (egress_tls_split_hello_reset), and you re-run it once the rule is in place. Then it waits up to 900 seconds for org-api and org-provisioner (status every 15 seconds), checks the two target groups, and requests https://<hostname>/ and /accounts expecting "302 to the Cognito hosted UI". If this machine cannot reach the console over your network, or the private DNS record is not in place yet, it warns and continues; re-run python3 orgctl.py settle from a machine on a routed network to verify sign-in.
10/13 Register this Organisation with AlphaAgent Console. Asks "Organisation machine credential for AlphaAgent Console": paste the credential from step 1 (not echoed). It is checked against the Console endpoint in RELEASE.txt and stored in the alphaagent-org-console-credential secret; done reads "Console accepted the credential (HTTP 200)". Skipped with "already holds a credential; re-validating it" when populated.
11/13 SAML federation into the user pool. Reprints the SP box, creates the break-glass owner if needed, then asks "Path to the downloaded federation metadata XML file": drag the file into the terminal. Connects the provider as AlphaAgentSSO and redeploys the app stack; password sign-in is off from here. Done: "SAML provider present, client flipped, listener parameter set".
12/13 Create the first Organisation administrator. Creates the break-glass user and its owner record if step 11 did not; otherwise prints "<email> already exists; left untouched" and "<email> granted the owner role in alphaagent-org-admins".
13/13 Verify the installation. Runs doctor, read-only. Its services group first waits up to 15 minutes for the rollout steps 10 and 11 restarted ("waiting for the services to finish rolling out before judging them"; doctor --no-wait opts out). Its private-network group checks that the attachment is available, every administrator range has an active route and the load balancer is internal; with outbound traffic through your Transit Gateway its egress group repeats the firewall check. Done is "N passed, 0 failed" and the Done banner; the groups and their remediations: Troubleshooting the install.
=== Done ===
Console: https://org.example.com
Run `python3 orgctl.py status` for the installed state.
Run `python3 orgctl.py doctor` to verify the install end to end.
What you should see
python3 orgctl.py status prints the progress file path, a thirteen-row table of steps with finish times, the SAML box, the hostname, the load balancer and the VPC ID, and the live status of the seven stacks; status --local skips the stack statuses and needs no AWS credentials. From a network your administrators' ranges cover, https://<hostname> redirects to your identity provider's sign-in page; from anywhere else the hostname does not answer. Measured: about 20 minutes wall clock from the first prompt to the Done banner, plus the time your network team takes to accept the attachment (the installer's own estimate for step 3 alone is 15 to 20 minutes; steps 9 and 13 wait up to 15 minutes each only when the services are slow to settle).
Other commands and flags
| Command or flag | Effect |
|---|---|
preflight, org-auth, foundation, private-network, push-image, seed-config, spa, app, settle, console-credential, saml, bootstrap-admin, doctor | Run one step on its own, to re-run or diagnose it. private-network re-applies the routes and puts back one deleted outside the stack. preflight on its own does not check the administrators' ranges; install checks them before it creates anything. |
status [--local] | The installed state, as above. |
reset | Asks "Clear all of the above? This makes no AWS call." and empties the progress file; AWS is unchanged. |
teardown | Deletes everything the installer created here (seven stacks, the Transit Gateway attachment, tables, buckets with contents, images, secrets with no recovery window, the user pool and its users, services, log groups, SSM parameter, Cloud Map namespace; never an org-target-account-role.yaml stack elsewhere, and never your private hosted zone's association with the VPC) after you type the account id, the region and DESTROY; otherwise "teardown not confirmed - aborted. Nothing was deleted." Non-interactive: --yes plus --i-understand-this-deletes-everything. Disassociate your private hosted zone from the VPC first, or remove the stale association from the zone afterwards. |
--region <code>, --profile <name> | The region (else AWS_REGION or AWS_DEFAULT_REGION, else the menu); a named credentials profile. |
--config <file> | Answers from JSON: region, environment, app_domain, cognito_prefix, acm_certificate_arn, vpc_cidr, console_access (only private on a new install), transit_gateway_id, user_access_cidrs, egress_mode (nat or transit_gateway), egress_ips (only with transit_gateway), break_glass_admin, console_credential, saml_metadata_path. user_access_cidrs and egress_ips may be a comma-separated string or a list. An invalid value is fatal: "<key> = <value>: <problem>". |
--yes | Accept every default, never prompt; needs a region and a --config supplying the answers without defaults (app_domain, acm_certificate_arn, vpc_cidr, transit_gateway_id, user_access_cidrs, egress_mode and, with transit_gateway, egress_ips, break_glass_admin, console_credential, saml_metadata_path); an existing Organisation is always resumed. |
--dry-run | No AWS write call; nothing is checkpointed. |
install --restart-from <step>, install --redo | Clear that checkpoint and every later one; re-run every step. |
--allow-data-loss | Upgrades only: let a stack update replace a data-bearing resource without confirmation; never implied by --yes. |
--skip-check <id> (preflight, install) | Skip one preflight check; the report prints "!! --skip-check suppressed: ... NOT checked and are NOT passing." |
--json (preflight, seed-config, doctor); doctor --no-wait; --help | JSON reports; judge the services without waiting for a rollout; every command and flag (install --help for one). |
ORGCTL_SETTLE_TIMEOUT, ORGCTL_STACK_TIMEOUT (environment variables) | Seconds settle waits for the services (default 900) and each stack operation may take (default 2400). |
Notes
- Stopping and resuming. Ctrl-C finishes the current step, prints "stopping before step N/13 (
<id>). re-run the same command to resume from where it stopped." and exits 130 (insidesettle, at once). Re-run the same command to resume; progress lives in.alphaagent-org-install.jsonbeside the bundle. - Resume menu, lock, state-file and timeout rules: Troubleshooting the install.